Audited anonymous-review AccessPath release

.gitignore

@@ -0,0 +1,10 @@
+# Inputs, weights, and generated outputs are intentionally never versioned.
+data/
+weights/
+outputs/
+logs/
+.env/
+.venv/
+__pycache__/
+*.py[cod]
+.DS_Store

README.md

@@ -0,0 +1,171 @@
+---
+license: other
+tags:
+- accessibility
+- amodal-completion
+- image-inpainting
+- 3d-reconstruction
+---
+
+# AccessPath
+
+AccessPath is an anonymous-review release for accessibility-scene amodal
+completion. It includes the full, finite GPU execution path from mask proposal
+through quality-gated 2D completion and visual 3D completion. The package also
+keeps two direct, mask-driven entry points:
+
+- **2D completion:** GPU inpainting that only changes the reviewed occluded
+  region and preserves source pixels elsewhere.
+- **Visual 3D completion:** a wrapper around the separately released
+  [Amodal3R](https://huggingface.co/Sm0kyWu/Amodal3R) backend that produces
+  Gaussian-splat and dense-mesh visual reconstructions from an RGB image and
+  an aligned three-value amodal mask.
+
+The five supported accessibility categories are `stairs`, `ramp`, `curb_cut`,
+`tactile_paving`, and `walkway`.
+
+## Relationship to prior work
+
+AccessPath is **inspired by and adapted from** established research on promptable
+segmentation, amodal completion, diffusion inpainting, monocular geometry, and
+visual 3D reconstruction. It is not presented as a reimplementation or a copy
+of any one prior system. The project-level contribution is the accessibility
+adaptation: category-specific target/obstacle prompts, a visible-hidden-amodal
+mask schema, constrained mask relations, mask-restricted 2D completion,
+geometry/quality gates, a finite Slurm workflow, and review-oriented outputs.
+
+When AccessPath actually calls an external model, that model remains an
+independent backend with its own code, weights, and license. The precise
+boundary between inspiration, optional comparison, and runtime use is listed
+in [docs/DEPENDENCIES_AND_WEIGHTS.md](docs/DEPENDENCIES_AND_WEIGHTS.md).
+
+## What is included
+
+This repository contains project-level pipeline, mask, 2D, depth/geometry,
+visual-3D adapter, verification, rendering, review-bundle, Slurm, and prompt
+configuration code. The complete process is documented in
+[docs/REPRODUCIBLE_PIPELINE.md](docs/REPRODUCIBLE_PIPELINE.md), and the
+stage-to-source mapping is in [docs/SOURCE_MANIFEST.md](docs/SOURCE_MANIFEST.md).
+For a beginner-oriented installation guide, exact dependency status, official
+model links, weight-download commands, and citation information, read
+[docs/DEPENDENCIES_AND_WEIGHTS.md](docs/DEPENDENCIES_AND_WEIGHTS.md) before
+running an experiment.
+
+It deliberately contains **no** source images, masks, model checkpoints,
+environments, experiment outputs, logs, author information, or
+machine-specific paths.
+
+The 100-image reviewer subset is not distributed yet. Its source-image and
+derived-mask redistribution status requires source-specific license and
+privacy clearance. A data card and a release manifest will be added only after
+that review is complete.
+
+## Setup
+
+Use Linux, Python 3.10+, a CUDA-capable GPU, and an environment compatible
+with the chosen models. Create a fresh environment, install PyTorch for the
+local CUDA version, then install the lightweight utilities:
+
+```bash
+python -m pip install -r requirements/runtime.txt
+python -m pip install diffusers transformers accelerate safetensors
+```
+
+The visual-3D backend additionally needs the official Amodal3R environment
+and its CUDA rasterizer dependencies. Follow the upstream installation guide;
+do not copy the upstream source tree or checkpoints into this repository.
+
+## Obtain models separately
+
+No weights are redistributed here. Download each dependency only after
+accepting its own license and access conditions.
+
+| Component | Official source | Used by |
+| --- | --- | --- |
+| Stable Diffusion inpainting | [`sd-legacy/stable-diffusion-inpainting`](https://huggingface.co/sd-legacy/stable-diffusion-inpainting) | 2D completion |
+| Amodal3R | [`Sm0kyWu/Amodal3R`](https://huggingface.co/Sm0kyWu/Amodal3R) | visual 3D completion |
+| SAM 3 (optional mask proposal stage) | [`facebook/sam3`](https://huggingface.co/facebook/sam3) | mask proposals only |
+
+Project-trained checkpoints are intentionally withheld during anonymous review.
+They should be released only after verifying the training-data permissions,
+base-model terms, privacy risk, and the paper's release policy.
+
+The optional VGGT path and the non-runtime related-work references
+(pix2gestalt, Open-World AMODAL, and Amodal Completion in the Wild) are
+identified explicitly in [docs/DEPENDENCIES_AND_WEIGHTS.md](docs/DEPENDENCIES_AND_WEIGHTS.md).
+They are not silently downloaded or executed by the default pipeline.
+
+## Input masks
+
+All masks must match the input RGB resolution. For 2D completion, provide the
+visible-target, amodal-target, and obstacle masks. For visual 3D completion,
+provide one aligned PNG with exactly these values:
+
+```text
+255  background
+188  visible target
+0    hidden target
+```
+
+The intended relations are `hidden = amodal AND NOT visible`, visible and
+obstacle are disjoint, and hidden is a subset of obstacle. Automatic masks are
+proposals and should be reviewed before they drive a completion result.
+
+## Run 2D completion
+
+```bash
+python accesspath.py 2d -- \
+  --image path/to/image.jpg \
+  --target-visible-mask path/to/target_visible.png \
+  --target-amodal-mask path/to/target_amodal.png \
+  --obstacle-mask path/to/obstacle.png \
+  --category stairs \
+  --model path/to/stable-diffusion-inpainting \
+  --output-dir outputs/example_2d \
+  --device cuda
+```
+
+The selected RGB result and its quality/provenance metadata are written under
+the output directory. Run `python accesspath.py 2d -- --help` for all options.
+
+## Run the complete pipeline
+
+The complete pipeline uses a bounded Slurm GPU job, so it queues for a GPU,
+persists its result directory, and exits once the requested image is complete:
+
+```bash
+python accesspath.py pipeline -- \
+  --image path/to/image.jpg \
+  --category stairs \
+  --output-dir outputs/stairs_demo
+```
+
+It runs mask proposals (or validates supplied reviewed masks), constrained
+amodal-mask inference, 2D completion, depth/geometry diagnostics, visual 3D,
+verification, and a compact review bundle. See
+[docs/REPRODUCIBLE_PIPELINE.md](docs/REPRODUCIBLE_PIPELINE.md) for environment
+variables, stage-by-stage behavior, outputs, and optional stage switches.
+
+## Run visual 3D completion
+
+Install the official Amodal3R runtime first, then run:
+
+```bash
+python accesspath.py 3d -- \
+  --image path/to/image.jpg \
+  --mask path/to/amodal_3value.png \
+  --model Sm0kyWu/Amodal3R \
+  --output-dir outputs/example_3d
+```
+
+This is a learned visual reconstruction, not metric geometry, a navigation
+safety label, or a guarantee of a watertight or scaled mesh. Run
+`python accesspath.py 3d -- --help` for output and rendering options.
+
+## Attribution and release boundary
+
+The 3D adapter calls Amodal3R and does not claim to reimplement that upstream
+model. Consult [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) and the model
+cards for all dependency terms. Repository code is provided for anonymous
+academic review; a final license and any project checkpoint release will be
+announced with the archival paper release.

THIRD_PARTY_NOTICES.md

@@ -0,0 +1,37 @@
+# Third-party notices
+
+AccessPath contains a project-level 2D inpainting orchestration layer and a
+small adapter for external visual-3D inference. It does not redistribute model
+weights, upstream source trees, datasets, or derived image assets.
+
+The project is inspired by prior work in amodal completion and visual 3D
+reconstruction, then adapted to accessibility-scene masks, categories, quality
+gates, and review outputs. Inspiration does not transfer authorship: an
+external model remains an external model whenever the runtime calls it.
+
+## External models and libraries
+
+- **Amodal3R** is an independently authored visual-3D backend. The adapter in
+  `tools/accessibility_3d_completion.py` imports its public Python package and
+  defaults to the upstream `Sm0kyWu/Amodal3R` model identifier. Its source,
+  checkpoint, and license remain those of the upstream project.
+- **Stable Diffusion inpainting** is accessed through Hugging Face Diffusers.
+  The user must obtain the selected checkpoint separately and comply with its
+  model card and license.
+- **SAM 3**, when used outside this minimal package to create mask proposals,
+  is separately licensed and may require access approval.
+- **Depth Anything V2** is the default depth/geometry diagnostic backend in
+  the full launcher. **VGGT** is an optional alternative depth/point-map
+  backend. Their code and checkpoints are separate downloads.
+- **pix2gestalt**, **Open-World AMODAL**, and **Amodal Completion in the Wild**
+  are not imported or executed by the AccessPath runtime; their URLs occur
+  only in related-work/comparison metadata.
+- PyTorch, OpenCV, Pillow, NumPy, ImageIO, Trimesh, Diffusers, Transformers,
+  Accelerate, and Safetensors retain their respective licenses.
+
+Renaming a wrapper or output does not transfer authorship or change any
+upstream license. No local model cache, environment, credential, dataset, or
+experiment artifact is included in this release.
+
+See [docs/DEPENDENCIES_AND_WEIGHTS.md](docs/DEPENDENCIES_AND_WEIGHTS.md) for
+the exact use status, official URLs, download commands, and citation guidance.

accessibilityamodal/__init__.py

@@ -0,0 +1,25 @@
+"""AccessibilityAmodal: project-owned accessibility completion utilities."""
+
+from .visual_completion import (
+    NEGATIVE_PROMPT,
+    PROMPTS,
+    build_visual_removal_mask,
+    candidate_quality,
+    derive_hidden_mask,
+    mask_statistics,
+    quality_flags_for_metrics,
+    select_candidate,
+)
+
+__all__ = [
+    "NEGATIVE_PROMPT",
+    "PROMPTS",
+    "build_visual_removal_mask",
+    "candidate_quality",
+    "derive_hidden_mask",
+    "mask_statistics",
+    "quality_flags_for_metrics",
+    "select_candidate",
+]
+
+__version__ = "0.1.0"

accessibilityamodal/category_overrides.py

@@ -0,0 +1,86 @@
+"""Apply human-reviewed accessibility category overrides by sample id."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+DEFAULT_CATEGORY_OVERRIDES_PATH = PROJECT_ROOT / "configs" / "accessibility_review_overrides.json"
+GEOMETRY_REVIEW_REQUIRED_CATEGORIES = frozenset(
+    {"stairs", "ramp", "curb_cut", "raised_curb"}
+)
+
+
+def load_reviewed_category_overrides(
+    path: str | Path | None = None,
+) -> dict[str, dict[str, Any]]:
+    source = DEFAULT_CATEGORY_OVERRIDES_PATH if path is None else Path(path)
+    if not source.is_absolute():
+        source = PROJECT_ROOT / source
+    if not source.is_file():
+        return {}
+    value = json.loads(source.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"Category override config must contain an object: {source}")
+    return {
+        str(sample_id): entry
+        for sample_id, entry in value.items()
+        if isinstance(entry, dict)
+    }
+
+
+def resolve_reviewed_category(
+    sample_id: str,
+    fallback_category: str,
+    overrides: Mapping[str, Mapping[str, Any]],
+) -> str:
+    fallback_category = str(fallback_category or "").strip().lower()
+    entry = overrides.get(sample_id)
+    if not entry or entry.get("category_reviewed") is not True:
+        return fallback_category
+    category = entry.get("category")
+    if not isinstance(category, str) or not category.strip():
+        raise ValueError(
+            f"Reviewed category override for {sample_id!r} must contain a non-empty category"
+        )
+    return category.strip().lower()
+
+
+def geometry_category_is_explicitly_reviewed(
+    sample_id: str,
+    metadata: Mapping[str, Any] | None,
+    overrides: Mapping[str, Mapping[str, Any]],
+) -> bool:
+    """Return whether the geometry-driving category itself was reviewed."""
+    if metadata and metadata.get("category_reviewed") is True:
+        return True
+    override = overrides.get(sample_id)
+    return bool(override and override.get("category_reviewed") is True)
+
+
+def resolve_geometry_category_for_modeling(
+    sample_id: str,
+    fallback_category: str,
+    metadata: Mapping[str, Any] | None,
+    overrides: Mapping[str, Mapping[str, Any]],
+    *,
+    allow_unreviewed_level_change: bool = False,
+) -> str:
+    """Resolve category and fail closed for unreviewed level-change geometry."""
+    category = resolve_reviewed_category(sample_id, fallback_category, overrides)
+    if not category:
+        raise ValueError(f"Sample {sample_id!r} has no category for 3D geometry routing")
+    if (
+        not allow_unreviewed_level_change
+        and category in GEOMETRY_REVIEW_REQUIRED_CATEGORIES
+        and not geometry_category_is_explicitly_reviewed(sample_id, metadata, overrides)
+    ):
+        raise ValueError(
+            f"Sample {sample_id!r} category {category!r} requires explicit category review "
+            "before selecting a 3D geometry prior. Run "
+            "tools/audit_accessibility_geometry_categories.py or add a reviewed override."
+        )
+    return category

accessibilityamodal/depth.py

@@ -0,0 +1,598 @@
+"""Generate a depth map for the accessibility geometry pipeline.
+
+This script keeps depth estimation separate from reconstruction so the core
+pipeline can run in lightweight environments and can optionally use heavier
+models such as Depth Anything V2 when their dependencies are installed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PIL import Image, ImageOps
+
+
+DEFAULT_DEPTH_MODEL = 'depth-anything/Depth-Anything-V2-Small-hf'
+DEFAULT_VGGT_MODEL = 'facebook/VGGT-1B'
+
+
+def depth_model_identity(
+    *,
+    engine: str,
+    model: str,
+    checkpoint: str | Path | None,
+    encoder: str,
+    metric_depth: bool,
+    vggt_model: str,
+) -> dict[str, Any]:
+    """Return an auditable third-party model identity without guessing revision."""
+
+    if engine == 'depth_anything_v2':
+        size = {
+            'vits': 'Small',
+            'vitb': 'Base',
+            'vitl': 'Large',
+            'vitg': 'Giant',
+        }.get(encoder, encoder)
+        checkpoint_name = Path(checkpoint).name.lower() if checkpoint else ''
+        dataset = (
+            'Hypersim'
+            if 'hypersim' in checkpoint_name
+            else 'VKITTI'
+            if 'vkitti' in checkpoint_name
+            else None
+        )
+        if metric_depth and dataset:
+            model_id = f'depth-anything/Depth-Anything-V2-Metric-{dataset}-{size}'
+        else:
+            model_id = f'depth-anything/Depth-Anything-V2-{size}'
+        return {
+            'model_id': model_id,
+            'family': 'Depth Anything V2',
+            'encoder': encoder,
+            'metric_training_dataset': dataset,
+            'license': 'Apache-2.0' if encoder == 'vits' else 'CC-BY-NC-4.0',
+            'third_party': True,
+            'revision': 'local_checkpoint_revision_unrecorded',
+            'revision_review_required_before_public_release': True,
+        }
+    if engine == 'transformers':
+        return {
+            'model_id': model,
+            'family': 'Transformers depth-estimation pipeline',
+            'license': 'see_upstream_model_card',
+            'third_party': True,
+            'revision': 'runtime_default_or_local_cache',
+            'revision_review_required_before_public_release': True,
+        }
+    if engine == 'vggt':
+        return {
+            'model_id': vggt_model,
+            'family': 'VGGT',
+            'license': 'see_upstream_model_card',
+            'third_party': True,
+            'revision': 'local_checkpoint_or_runtime_default',
+            'revision_review_required_before_public_release': True,
+        }
+    return {
+        'model_id': 'opencv_depth_fallback',
+        'family': 'nonlearned_fallback',
+        'third_party': True,
+    }
+
+
+def read_rgb(path: str | Path, max_size: int | None = None) -> Image.Image:
+    image = ImageOps.exif_transpose(Image.open(path)).convert('RGB')
+    if max_size and max(image.size) > max_size:
+        scale = max_size / max(image.size)
+        size = (round(image.size[0] * scale), round(image.size[1] * scale))
+        image = image.resize(size, Image.Resampling.LANCZOS)
+    return image
+
+
+def normalize_depth(depth: np.ndarray, near: float, far: float, invert: bool) -> np.ndarray:
+    depth = depth.astype(np.float32)
+    valid = np.isfinite(depth)
+    if not np.any(valid):
+        raise ValueError('Depth prediction contains no finite values')
+
+    values = depth[valid]
+    lo, hi = np.percentile(values, [1, 99])
+    if hi <= lo:
+        hi = lo + 1.0
+    norm = np.clip((depth - lo) / (hi - lo), 0.0, 1.0)
+    if invert:
+        norm = 1.0 - norm
+    return near + norm * (far - near)
+
+
+def resize_float_map(values: np.ndarray, size: tuple[int, int]) -> np.ndarray:
+    image = Image.fromarray(values.astype(np.float32), mode='F')
+    image = image.resize(size, Image.Resampling.BILINEAR)
+    return np.asarray(image, dtype=np.float32)
+
+
+def colorize_confidence(confidence: np.ndarray) -> Image.Image:
+    confidence = confidence.astype(np.float32)
+    valid = np.isfinite(confidence)
+    if not np.any(valid):
+        return Image.fromarray(np.zeros(confidence.shape, dtype=np.uint8), mode='L')
+    lo, hi = np.percentile(confidence[valid], [2, 98])
+    if hi <= lo:
+        hi = lo + 1.0
+    vis = np.clip((confidence - lo) / (hi - lo), 0.0, 1.0)
+    vis[~valid] = 0
+    return Image.fromarray((vis * 255).astype(np.uint8), mode='L')
+
+
+def preprocess_square_tensor(image: Image.Image, target_size: int):
+    import torch
+
+    width, height = image.size
+    max_dim = max(width, height)
+    left = (max_dim - width) // 2
+    top = (max_dim - height) // 2
+    scale = target_size / max_dim
+    crop = (
+        left * scale,
+        top * scale,
+        (left + width) * scale,
+        (top + height) * scale,
+    )
+    square = Image.new('RGB', (max_dim, max_dim), (0, 0, 0))
+    square.paste(image, (left, top))
+    square = square.resize((target_size, target_size), Image.Resampling.BICUBIC)
+    array = np.asarray(square, dtype=np.float32) / 255.0
+    tensor = torch.from_numpy(array).permute(2, 0, 1).contiguous()
+    return tensor[None], crop
+
+
+def crop_and_resize_prediction(values: np.ndarray, crop: tuple[float, float, float, float], size: tuple[int, int]) -> np.ndarray:
+    left, top, right, bottom = crop
+    h, w = values.shape[:2]
+    left_i = max(0, min(w - 1, int(np.floor(left))))
+    top_i = max(0, min(h - 1, int(np.floor(top))))
+    right_i = max(left_i + 1, min(w, int(np.ceil(right))))
+    bottom_i = max(top_i + 1, min(h, int(np.ceil(bottom))))
+    cropped = values[top_i:bottom_i, left_i:right_i]
+    if values.ndim == 2:
+        return resize_float_map(cropped, size)
+    channels = [resize_float_map(cropped[..., channel], size) for channel in range(values.shape[-1])]
+    return np.stack(channels, axis=-1).astype(np.float32)
+
+
+def write_point_cloud_ply(
+    path: Path,
+    points: np.ndarray,
+    colors: np.ndarray,
+    confidence: np.ndarray | None,
+    confidence_threshold: float,
+    max_points: int,
+) -> int:
+    valid = np.all(np.isfinite(points), axis=-1) & (points[..., 2] > 0)
+    if confidence is not None:
+        valid &= np.isfinite(confidence) & (confidence >= confidence_threshold)
+    ys, xs = np.where(valid)
+    if ys.size == 0:
+        selected = np.array([], dtype=np.int64)
+    elif max_points > 0 and ys.size > max_points:
+        selected = np.linspace(0, ys.size - 1, max_points, dtype=np.int64)
+    else:
+        selected = np.arange(ys.size, dtype=np.int64)
+    pts = points[ys[selected], xs[selected]]
+    cols = colors[ys[selected], xs[selected]]
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open('w', encoding='ascii') as handle:
+        handle.write('ply\nformat ascii 1.0\n')
+        handle.write(f'element vertex {len(pts)}\n')
+        handle.write('property float x\nproperty float y\nproperty float z\n')
+        handle.write('property uchar red\nproperty uchar green\nproperty uchar blue\n')
+        handle.write('end_header\n')
+        for point, color in zip(pts, cols):
+            handle.write(
+                f'{point[0]:.6f} {point[1]:.6f} {point[2]:.6f} '
+                f'{int(color[0])} {int(color[1])} {int(color[2])}\n'
+            )
+    return int(len(pts))
+
+
+def heuristic_depth(image: Image.Image, near: float, far: float) -> np.ndarray:
+    """Build a deterministic perspective prior from image position and edges."""
+    rgb = np.asarray(image, dtype=np.float32) / 255.0
+    h, w = rgb.shape[:2]
+    yy = np.linspace(0.0, 1.0, h, dtype=np.float32)[:, None]
+    depth = far - yy * (far - near)
+    depth = np.repeat(depth, w, axis=1)
+
+    gray = 0.299 * rgb[..., 0] + 0.587 * rgb[..., 1] + 0.114 * rgb[..., 2]
+    grad_y = np.abs(np.gradient(gray, axis=0))
+    if np.isfinite(grad_y).any() and float(grad_y.max()) > 0:
+        grad_y = grad_y / float(grad_y.max())
+        depth -= 0.08 * (far - near) * grad_y.astype(np.float32)
+    return np.clip(depth, min(near, far), max(near, far)).astype(np.float32)
+
+
+def resolve_device(device: str) -> int | str:
+    if device == 'cpu':
+        return -1
+    if device == 'auto':
+        import torch
+
+        return 0 if torch.cuda.is_available() else -1
+    if device.startswith('cuda'):
+        if ':' in device:
+            return int(device.split(':', 1)[1])
+        return 0
+    return device
+
+
+def transformers_depth(image: Image.Image, model: str, device: str) -> np.ndarray:
+    try:
+        from transformers import pipeline
+    except ImportError as exc:
+        raise RuntimeError('transformers is not installed; install optional depth dependencies first') from exc
+
+    estimator = pipeline('depth-estimation', model=model, device=resolve_device(device))
+    result: dict[str, Any] = estimator(image)
+    if 'predicted_depth' in result:
+        predicted = result['predicted_depth']
+        if hasattr(predicted, 'detach'):
+            predicted = predicted.detach().cpu().numpy()
+        depth = np.asarray(predicted, dtype=np.float32)
+        if depth.ndim == 3:
+            depth = depth.squeeze()
+    elif 'depth' in result:
+        depth = np.asarray(result['depth'], dtype=np.float32)
+    else:
+        raise RuntimeError(f'Unexpected depth-estimation result keys: {sorted(result)}')
+
+    if depth.shape[:2] != (image.height, image.width):
+        depth_img = Image.fromarray(depth.astype(np.float32), mode='F')
+        depth_img = depth_img.resize(image.size, Image.Resampling.BILINEAR)
+        depth = np.asarray(depth_img, dtype=np.float32)
+    return depth.astype(np.float32)
+
+
+def resolve_torch_device(device: str) -> str:
+    if device != 'auto':
+        return device
+    import torch
+
+    return 'cuda' if torch.cuda.is_available() else 'cpu'
+
+
+def depth_anything_v2_depth(
+    image: Image.Image,
+    repo: str | Path,
+    checkpoint: str | Path,
+    encoder: str,
+    device: str,
+    input_size: int,
+    metric: bool,
+    max_depth: float,
+) -> np.ndarray:
+    repo = Path(repo).resolve()
+    checkpoint = Path(checkpoint).resolve()
+    if not checkpoint.exists():
+        raise FileNotFoundError(f'Depth Anything V2 checkpoint not found: {checkpoint}')
+    if not repo.exists():
+        raise FileNotFoundError(f'Depth Anything V2 repo not found: {repo}')
+    source_root = repo / 'metric_depth' if metric else repo
+    if not source_root.exists():
+        raise FileNotFoundError(f'Depth Anything V2 source root not found: {source_root}')
+
+    sys.path.insert(0, str(source_root))
+    import torch
+    from depth_anything_v2.dpt import DepthAnythingV2
+    import depth_anything_v2.dinov2_layers.attention as da_attention
+    import depth_anything_v2.dinov2_layers.block as da_block
+
+    model_configs = {
+        'vits': {'encoder': 'vits', 'features': 64, 'out_channels': [48, 96, 192, 384]},
+        'vitb': {'encoder': 'vitb', 'features': 128, 'out_channels': [96, 192, 384, 768]},
+        'vitl': {'encoder': 'vitl', 'features': 256, 'out_channels': [256, 512, 1024, 1024]},
+        'vitg': {'encoder': 'vitg', 'features': 384, 'out_channels': [1536, 1536, 1536, 1536]},
+    }
+    if encoder not in model_configs:
+        raise ValueError(f'Unsupported Depth Anything V2 encoder: {encoder}')
+    config = dict(model_configs[encoder])
+    if metric:
+        config['max_depth'] = max_depth
+
+    torch_device = resolve_torch_device(device)
+    # The vendored Depth Anything V2 DINOv2 blocks prefer xFormers when it is
+    # importable, but the available xFormers kernels do not support every
+    # server GPU/dtype combination, including RTX 5090 sm_120 with float32.
+    # Use plain PyTorch attention for reproducible CPU and Slurm inference.
+    da_attention.XFORMERS_AVAILABLE = False
+    da_block.XFORMERS_AVAILABLE = False
+
+    model = DepthAnythingV2(**config)
+    model.load_state_dict(torch.load(str(checkpoint), map_location='cpu'))
+    model = model.to(torch_device).eval()
+
+    # ``image`` was EXIF-normalized and optionally downscaled by ``read_rgb``.
+    # Depth Anything's infer_image receives BGR when loaded via OpenCV, so
+    # preserve that channel convention without reopening the raw JPEG.
+    raw = np.asarray(image.convert('RGB'))[:, :, ::-1].copy()
+
+    with torch.inference_mode():
+        depth = model.infer_image(raw, input_size)
+    return depth.astype(np.float32)
+
+
+def load_vggt_model(
+    repo: str | Path,
+    model_id: str,
+    checkpoint: str | Path | None,
+    device: str,
+):
+    repo = Path(repo).resolve()
+    if not repo.exists():
+        raise FileNotFoundError(f'VGGT repo not found: {repo}')
+    if str(repo) not in sys.path:
+        sys.path.insert(0, str(repo))
+
+    import torch
+    from vggt.models.vggt import VGGT
+
+    torch_device = resolve_torch_device(device)
+    # We only need camera/depth/point for accessibility geometry. Disabling
+    # track avoids loading the point-tracking branch and lowers memory use.
+    model = VGGT(enable_track=False)
+    if checkpoint:
+        checkpoint = Path(checkpoint).resolve()
+        if not checkpoint.exists():
+            raise FileNotFoundError(f'VGGT checkpoint not found: {checkpoint}')
+        state = torch.load(str(checkpoint), map_location='cpu')
+        if isinstance(state, dict) and 'model' in state:
+            state = state['model']
+    else:
+        local_model = Path(model_id)
+        if local_model.exists():
+            model_path = local_model / 'model.pt' if local_model.is_dir() else local_model
+            if not model_path.exists():
+                raise FileNotFoundError(f'VGGT local model checkpoint not found: {model_path}')
+        else:
+            from huggingface_hub import hf_hub_download
+
+            model_path = Path(hf_hub_download(repo_id=model_id, filename='model.pt'))
+        state = torch.load(str(model_path), map_location='cpu')
+        if isinstance(state, dict) and 'model' in state:
+            state = state['model']
+    missing, unexpected = model.load_state_dict(state, strict=False)
+    if missing:
+        print(f'VGGT checkpoint missing keys: {len(missing)}', file=sys.stderr)
+    if unexpected:
+        print(f'VGGT checkpoint unexpected keys: {len(unexpected)}', file=sys.stderr)
+    model = model.to(torch_device).eval()
+    return model, torch_device
+
+
+def vggt_predict_depth(
+    image: Image.Image,
+    model,
+    device: str,
+    input_size: int,
+    near: float,
+    far: float,
+    invert: bool,
+    keep_raw_depth: bool,
+) -> dict[str, np.ndarray]:
+    import torch
+
+    tensor, crop = preprocess_square_tensor(image, input_size)
+    tensor = tensor.to(device)
+    if device.startswith('cuda'):
+        major = torch.cuda.get_device_capability()[0]
+        dtype = torch.bfloat16 if major >= 8 else torch.float16
+        autocast = torch.cuda.amp.autocast(dtype=dtype)
+    else:
+        autocast = torch.autocast(device_type='cpu', enabled=False)
+
+    with torch.inference_mode():
+        with autocast:
+            predictions = model(tensor)
+
+    raw_depth = predictions['depth'][0, 0, ..., 0].detach().float().cpu().numpy()
+    depth_conf = predictions['depth_conf'][0, 0].detach().float().cpu().numpy()
+    point_map = predictions['world_points'][0, 0].detach().float().cpu().numpy()
+    point_conf = predictions['world_points_conf'][0, 0].detach().float().cpu().numpy()
+
+    raw_depth = crop_and_resize_prediction(raw_depth, crop, image.size)
+    depth_conf = crop_and_resize_prediction(depth_conf, crop, image.size)
+    point_map = crop_and_resize_prediction(point_map, crop, image.size)
+    point_conf = crop_and_resize_prediction(point_conf, crop, image.size)
+    depth = raw_depth if keep_raw_depth else normalize_depth(raw_depth, near, far, invert)
+    return {
+        'depth': depth.astype(np.float32),
+        'raw_depth': raw_depth.astype(np.float32),
+        'depth_conf': depth_conf.astype(np.float32),
+        'world_points': point_map.astype(np.float32),
+        'world_points_conf': point_conf.astype(np.float32),
+    }
+
+
+def save_depth_vis(path: str | Path, depth: np.ndarray) -> None:
+    valid = np.isfinite(depth)
+    values = depth[valid]
+    if values.size == 0:
+        vis = np.zeros(depth.shape, dtype=np.uint8)
+    else:
+        lo, hi = np.percentile(values, [2, 98])
+        if hi <= lo:
+            hi = lo + 1.0
+        vis = np.clip((depth - lo) / (hi - lo), 0.0, 1.0)
+        vis = (vis * 255).astype(np.uint8)
+    Image.fromarray(vis, mode='L').save(path)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description='Generate relative depth for accessibility geometry completion.')
+    parser.add_argument('--image', required=True, help='Input RGB image.')
+    parser.add_argument('--output-depth', required=True, help='Output .npy depth path.')
+    parser.add_argument('--output-vis', default=None, help='Optional grayscale depth visualization path.')
+    parser.add_argument('--manifest', default=None, help='Optional JSON manifest path.')
+    parser.add_argument('--engine', choices=['heuristic', 'transformers', 'depth_anything_v2', 'vggt'], default='heuristic')
+    parser.add_argument('--model', default=DEFAULT_DEPTH_MODEL, help='Transformers depth-estimation model id or local path.')
+    parser.add_argument('--device', default='auto', help='auto, cpu, cuda, cuda:0, or a transformers device string.')
+    parser.add_argument('--depth-anything-repo', default='../diffusion-vas/models/Depth_Anything_V2', help='Local Depth Anything V2 source repo.')
+    parser.add_argument('--checkpoint', default=None, help='Depth Anything V2 .pth checkpoint for --engine depth_anything_v2.')
+    parser.add_argument('--encoder', choices=['vits', 'vitb', 'vitl', 'vitg'], default='vitl')
+    parser.add_argument('--metric-depth', action='store_true', help='Treat the Depth Anything V2 checkpoint as a metric-depth model and do not near/far normalize.')
+    parser.add_argument('--max-depth', type=float, default=20.0, help='Metric Depth Anything max depth in meters.')
+    parser.add_argument('--input-size', type=int, default=518, help='Depth Anything V2 inference input size.')
+    parser.add_argument('--near', type=float, default=1.0, help='Depth value assigned to the near end after normalization.')
+    parser.add_argument('--far', type=float, default=6.0, help='Depth value assigned to the far end after normalization.')
+    parser.add_argument('--invert-depth', action='store_true', help='Invert predicted relative depth before near/far normalization.')
+    parser.add_argument('--max-size', type=int, default=1280, help='Resize longest side before inference. Use 0 to keep original size.')
+    parser.add_argument('--vggt-repo', default='vggt', help='Local facebookresearch/VGGT checkout.')
+    parser.add_argument('--vggt-model', default=DEFAULT_VGGT_MODEL, help='Hugging Face model id or local VGGT model directory.')
+    parser.add_argument('--vggt-checkpoint', default=None, help='Optional local VGGT model.pt checkpoint.')
+    parser.add_argument('--vggt-input-size', type=int, default=518, help='Square VGGT inference resolution.')
+    parser.add_argument('--vggt-keep-raw-depth', action='store_true', help='Do not near/far normalize VGGT depth before saving --output-depth.')
+    parser.add_argument('--output-conf', default=None, help='Optional output .npy confidence map path.')
+    parser.add_argument('--output-conf-vis', default=None, help='Optional output confidence visualization path.')
+    parser.add_argument('--output-raw-depth', default=None, help='Optional output raw VGGT depth .npy path.')
+    parser.add_argument('--output-world-points', default=None, help='Optional output VGGT world point map .npy path.')
+    parser.add_argument('--output-point-conf', default=None, help='Optional output VGGT world point confidence .npy path.')
+    parser.add_argument('--output-point-cloud', default=None, help='Optional output VGGT point cloud .ply path.')
+    parser.add_argument('--point-conf-threshold', type=float, default=1.0, help='VGGT point confidence threshold for --output-point-cloud.')
+    parser.add_argument('--max-point-cloud-points', type=int, default=120000, help='Maximum VGGT point-cloud vertices to export.')
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    max_size = None if args.max_size == 0 else args.max_size
+    image = read_rgb(args.image, max_size=max_size)
+
+    if args.engine == 'heuristic':
+        raw_depth = heuristic_depth(image, args.near, args.far)
+        depth = raw_depth
+    elif args.engine == 'transformers':
+        raw_depth = transformers_depth(image, args.model, args.device)
+        depth = normalize_depth(raw_depth, args.near, args.far, args.invert_depth)
+    elif args.engine == 'depth_anything_v2':
+        raw_depth = depth_anything_v2_depth(
+            image,
+            args.depth_anything_repo,
+            args.checkpoint,
+            args.encoder,
+            args.device,
+            args.input_size,
+            args.metric_depth,
+            args.max_depth,
+        )
+        depth = raw_depth if args.metric_depth else normalize_depth(raw_depth, args.near, args.far, args.invert_depth)
+    else:
+        model, torch_device = load_vggt_model(
+            args.vggt_repo,
+            args.vggt_model,
+            args.vggt_checkpoint,
+            args.device,
+        )
+        prediction = vggt_predict_depth(
+            image,
+            model,
+            torch_device,
+            args.vggt_input_size,
+            args.near,
+            args.far,
+            args.invert_depth,
+            args.vggt_keep_raw_depth,
+        )
+        depth = prediction['depth']
+        raw_depth = prediction['raw_depth']
+        if args.output_conf:
+            Path(args.output_conf).parent.mkdir(parents=True, exist_ok=True)
+            np.save(Path(args.output_conf), prediction['depth_conf'].astype(np.float32))
+        if args.output_conf_vis:
+            Path(args.output_conf_vis).parent.mkdir(parents=True, exist_ok=True)
+            colorize_confidence(prediction['depth_conf']).save(args.output_conf_vis)
+        if args.output_raw_depth:
+            Path(args.output_raw_depth).parent.mkdir(parents=True, exist_ok=True)
+            np.save(Path(args.output_raw_depth), prediction['raw_depth'].astype(np.float32))
+        if args.output_world_points:
+            Path(args.output_world_points).parent.mkdir(parents=True, exist_ok=True)
+            np.save(Path(args.output_world_points), prediction['world_points'].astype(np.float32))
+        if args.output_point_conf:
+            Path(args.output_point_conf).parent.mkdir(parents=True, exist_ok=True)
+            np.save(Path(args.output_point_conf), prediction['world_points_conf'].astype(np.float32))
+        if args.output_point_cloud:
+            rgb = np.asarray(image.convert('RGB'), dtype=np.uint8)
+            point_count = write_point_cloud_ply(
+                Path(args.output_point_cloud),
+                prediction['world_points'],
+                rgb,
+                prediction['world_points_conf'],
+                args.point_conf_threshold,
+                args.max_point_cloud_points,
+            )
+            print(f'Wrote VGGT point cloud to {args.output_point_cloud} ({point_count} points)')
+
+    output_depth = Path(args.output_depth)
+    output_depth.parent.mkdir(parents=True, exist_ok=True)
+    np.save(output_depth, depth.astype(np.float32))
+
+    output_vis = Path(args.output_vis) if args.output_vis else output_depth.with_suffix('.png')
+    output_vis.parent.mkdir(parents=True, exist_ok=True)
+    save_depth_vis(output_vis, depth)
+
+    note = 'Metric monocular depth estimate; calibrate intrinsics/scale before path-planning use.'
+    if args.engine == 'vggt':
+        note = 'VGGT single-view/few-view geometry estimate; scale is not calibrated metric ground truth.'
+    elif args.engine != 'depth_anything_v2' or not args.metric_depth:
+        note = 'Relative monocular depth; use calibrated metric depth for path-planning truth.'
+
+    model_identity = depth_model_identity(
+        engine=args.engine,
+        model=args.model,
+        checkpoint=args.checkpoint,
+        encoder=args.encoder,
+        metric_depth=args.metric_depth,
+        vggt_model=args.vggt_model,
+    )
+    manifest = {
+        'image': args.image,
+        'raster_orientation_policy': 'RGB is decoded with PIL ImageOps.exif_transpose before depth inference.',
+        'display_raster_size': {'width': image.width, 'height': image.height},
+        'engine': args.engine,
+        'model': model_identity['model_id'],
+        'model_identity': model_identity,
+        'depth_anything_repo': args.depth_anything_repo if args.engine == 'depth_anything_v2' else None,
+        'checkpoint': args.checkpoint if args.engine == 'depth_anything_v2' else None,
+        'encoder': args.encoder if args.engine == 'depth_anything_v2' else None,
+        'vggt_repo': args.vggt_repo if args.engine == 'vggt' else None,
+        'vggt_model': args.vggt_model if args.engine == 'vggt' else None,
+        'vggt_checkpoint': args.vggt_checkpoint if args.engine == 'vggt' else None,
+        'vggt_input_size': args.vggt_input_size if args.engine == 'vggt' else None,
+        'vggt_keep_raw_depth': args.vggt_keep_raw_depth if args.engine == 'vggt' else None,
+        'metric_depth': args.metric_depth if args.engine == 'depth_anything_v2' else None,
+        'max_depth': args.max_depth if args.metric_depth else None,
+        'device': args.device if args.engine in {'transformers', 'depth_anything_v2', 'vggt'} else None,
+        'output_depth': str(output_depth),
+        'output_vis': str(output_vis),
+        'output_conf': args.output_conf if args.engine == 'vggt' else None,
+        'output_raw_depth': args.output_raw_depth if args.engine == 'vggt' else None,
+        'output_world_points': args.output_world_points if args.engine == 'vggt' else None,
+        'output_point_cloud': args.output_point_cloud if args.engine == 'vggt' else None,
+        'near': args.near,
+        'far': args.far,
+        'invert_depth': args.invert_depth,
+        'shape': list(depth.shape),
+        'note': note,
+    }
+    manifest_path = Path(args.manifest) if args.manifest else output_depth.with_name('depth_manifest.json')
+    manifest_path.write_text(json.dumps(manifest, indent=2), encoding='utf-8')
+    print(f'Wrote depth to {output_depth}')
+    print(f'Wrote depth visualization to {output_vis}')
+
+
+if __name__ == '__main__':
+    main()

accessibilityamodal/geometry_analysis.py

@@ -0,0 +1,607 @@
+"""Structured accessibility geometry constraints for 3D amodal completion.
+
+The functions in this module convert the deterministic outputs of
+``accessibilityamodal.reconstruct`` into a JSON-ready report. The report is intended for
+navigation-risk review and downstream reconstruction code, not for visual
+plausibility scoring.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import cv2
+import numpy as np
+
+
+VALID_CATEGORIES = {
+    "stairs",
+    "ramp",
+    "walkway",
+    "curb_cut",
+    "raised_curb",
+    "tactile_paving",
+    "unknown",
+}
+CONTINUOUS_CATEGORIES = {"ramp", "walkway", "curb_cut", "raised_curb", "tactile_paving"}
+
+
+def _round(value: float | int | None, digits: int = 6) -> float | None:
+    if value is None:
+        return None
+    return round(float(value), digits)
+
+
+def _ratio(numerator: int | float, denominator: int | float) -> float:
+    if denominator <= 0:
+        return 0.0
+    return float(numerator) / float(denominator)
+
+
+def normalize_category(category: str | None, geometry_mode: str) -> str:
+    value = (category or "").strip().lower()
+    if value == "walkable":
+        value = "walkway"
+    if value in VALID_CATEGORIES:
+        return value
+    if geometry_mode == "stairs":
+        return "stairs"
+    if geometry_mode == "ramp":
+        return "ramp"
+    if geometry_mode == "walkable":
+        return "walkway"
+    return "unknown"
+
+
+def _step_interval_consistency(edges_y: list[int]) -> str:
+    if len(edges_y) < 3:
+        return "unknown"
+    gaps = np.diff(np.array(sorted(edges_y), dtype=np.float32))
+    mean_gap = float(np.mean(gaps))
+    if mean_gap <= 1e-6:
+        return "unknown"
+    variation = float(np.std(gaps) / mean_gap)
+    if variation < 0.18:
+        return "high"
+    if variation < 0.35:
+        return "medium"
+    return "low"
+
+
+def _slope_direction_from_depth(depth: np.ndarray, target: np.ndarray) -> str:
+    if not np.any(target):
+        return "unknown"
+    valid = target & np.isfinite(depth) & (depth > 0)
+    if int(valid.sum()) < 32:
+        return "unknown"
+    ys = np.where(valid)[0]
+    middle = float(np.median(ys))
+    upper = valid & (np.indices(valid.shape)[0] <= middle)
+    lower = valid & (np.indices(valid.shape)[0] > middle)
+    if int(upper.sum()) < 16 or int(lower.sum()) < 16:
+        return "unknown"
+    upper_depth = float(np.median(depth[upper]))
+    lower_depth = float(np.median(depth[lower]))
+    scale = max(abs(upper_depth), abs(lower_depth), 1e-6)
+    if abs(upper_depth - lower_depth) / scale < 0.02:
+        return "unknown"
+    return "away_from_camera" if upper_depth > lower_depth else "toward_camera"
+
+
+def _visible_evidence(
+    category: str,
+    visible_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    hidden_mask: np.ndarray,
+    obstacle_mask: np.ndarray,
+    depth: np.ndarray,
+    edges_y: list[int],
+    stair_edge_confidence: float,
+    stair_edge_coverage: float,
+    completion_method: str,
+) -> list[dict[str, Any]]:
+    evidence: list[dict[str, Any]] = []
+    amodal_area = int(amodal_mask.sum())
+    visible_area = int(visible_mask.sum())
+    hidden_area = int(hidden_mask.sum())
+    obstacle_overlap = int((obstacle_mask & amodal_mask).sum())
+
+    if visible_area > 0:
+        evidence.append(
+            {
+                "type": "boundary",
+                "description": "visible target mask defines the observed support boundary",
+                "confidence": _round(min(0.95, 0.35 + 0.60 * _ratio(visible_area, max(amodal_area, 1)))),
+            }
+        )
+
+    if hidden_area > 0 or obstacle_overlap > 0:
+        evidence.append(
+            {
+                "type": "occlusion",
+                "description": "hidden target support is constrained by amodal-minus-visible and obstacle overlap",
+                "confidence": _round(min(0.95, 0.30 + 0.60 * _ratio(obstacle_overlap, max(hidden_area, 1)))),
+            }
+        )
+
+    if category == "stairs" and edges_y:
+        evidence.append(
+            {
+                "type": "repeated_step",
+                "description": f"{len(edges_y)} candidate stair tread/riser boundary rows detected",
+                "confidence": _round(max(stair_edge_confidence, min(stair_edge_coverage, 1.0) * 0.75)),
+            }
+        )
+
+    if category in CONTINUOUS_CATEGORIES and "plane" in completion_method:
+        evidence.append(
+            {
+                "type": (
+                    "slope"
+                    if category == "ramp"
+                    else "curb_boundary"
+                    if category == "raised_curb"
+                    else "boundary"
+                ),
+                "description": (
+                    "visible curb support is completed as one continuous surface without repeated steps"
+                    if category == "raised_curb"
+                    else "visible support is completed with a robust continuous-surface prior"
+                ),
+                "confidence": 0.70,
+            }
+        )
+
+    valid_depth = amodal_mask & np.isfinite(depth) & (depth > 0)
+    if int(valid_depth.sum()) >= 128:
+        rows = np.where(valid_depth)[0]
+        row_span = max(int(rows.max() - rows.min()), 1)
+        depth_values = depth[valid_depth]
+        depth_span = float(np.percentile(depth_values, 90) - np.percentile(depth_values, 10))
+        scale = max(float(np.median(depth_values)), 1e-6)
+        if depth_span / scale > 0.02 and row_span > 8:
+            evidence.append(
+                {
+                    "type": "depth_gradient",
+                    "description": "target depth varies coherently across the support region",
+                    "confidence": _round(min(0.80, depth_span / scale)),
+                }
+            )
+    return evidence
+
+
+def _connected_hidden_regions(
+    category: str,
+    hidden_mask: np.ndarray,
+    completion_method: str,
+    mean_hidden_confidence: float,
+    edges_y: list[int],
+) -> list[dict[str, Any]]:
+    if not np.any(hidden_mask):
+        return []
+    labels_count, labels, stats, _ = cv2.connectedComponentsWithStats(
+        hidden_mask.astype(np.uint8), connectivity=8
+    )
+    regions: list[dict[str, Any]] = []
+    areas = [
+        (idx, int(stats[idx, cv2.CC_STAT_AREA]))
+        for idx in range(1, labels_count)
+        if int(stats[idx, cv2.CC_STAT_AREA]) > 0
+    ]
+    areas.sort(key=lambda item: item[1], reverse=True)
+    total = max(int(hidden_mask.sum()), 1)
+    for serial, (idx, area) in enumerate(areas[:12], start=1):
+        if category == "stairs" and len(edges_y) >= 2:
+            basis = "repeated_steps"
+            description = "complete the hidden support by repeating the visible tread/riser pattern"
+        elif category in {"ramp", "walkway", "curb_cut", "raised_curb"} and "plane" in completion_method:
+            basis = "plane_continuity"
+            description = (
+                "continue one curb top/face support through the hidden region without stair bands"
+                if category == "raised_curb"
+                else "project hidden pixels onto the fitted visible support plane"
+            )
+        elif category == "tactile_paving":
+            basis = "boundary_continuity"
+            description = "preserve the narrow tactile strip footprint through the hidden region"
+        elif "inpaint" in completion_method:
+            basis = "depth_interpolation"
+            description = "use local depth interpolation because stronger structural evidence is unavailable"
+        else:
+            basis = "uncertain"
+            description = "insufficient structural evidence for confident hidden completion"
+        regions.append(
+            {
+                "region_id": f"hidden_{serial}",
+                "completion_basis": basis,
+                "description": description,
+                "confidence": _round(min(0.95, mean_hidden_confidence * (0.50 + 0.50 * area / total))),
+            }
+        )
+    return regions
+
+
+def _amodal_quality(
+    target_present: bool,
+    visible_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    hidden_mask: np.ndarray,
+    mean_hidden_confidence: float,
+    used_regular_fallback_edges: bool,
+) -> str:
+    if not target_present:
+        return "bad"
+    amodal_area = int(amodal_mask.sum())
+    visible_ratio = _ratio(int(visible_mask.sum()), amodal_area)
+    hidden_ratio = _ratio(int(hidden_mask.sum()), amodal_area)
+    if visible_ratio < 0.02:
+        return "bad"
+    if used_regular_fallback_edges or mean_hidden_confidence < 0.30:
+        return "uncertain"
+    if visible_ratio >= 0.20 and (hidden_ratio == 0.0 or mean_hidden_confidence >= 0.50):
+        return "good"
+    if visible_ratio >= 0.05:
+        return "partial"
+    return "uncertain"
+
+
+def _geometry_model_type(category: str, geometry_mode: str) -> str:
+    if category == "raised_curb":
+        return "raised_curb_prism"
+    if category == "stairs" or geometry_mode == "stairs":
+        return "stair_steps"
+    if category == "curb_cut":
+        return "curb_cut_planes"
+    if category == "tactile_paving":
+        return "tactile_strip"
+    if category in {"ramp", "walkway"}:
+        return "single_plane"
+    return "uncertain"
+
+
+def _hidden_depth_rule(category: str, completion_method: str) -> str:
+    if category == "stairs":
+        return "repeat_stair_geometry"
+    if category in {"ramp", "walkway", "curb_cut", "raised_curb", "tactile_paving"} and "plane" in completion_method:
+        return "fit_to_plane"
+    if "inpaint" in completion_method:
+        return "interpolate_between_boundaries"
+    return "uncertain"
+
+
+def _recommended_action(category: str, geometry_confidence: float) -> tuple[str, str]:
+    if geometry_confidence < 0.30:
+        return "manual_review", "Evidence is weak; do not generate a navigation mesh without review."
+    if category == "stairs":
+        return (
+            "stair_regularization",
+            "Fit repeated tread/riser bands and complete hidden depth by stair periodicity.",
+        )
+    if category == "curb_cut":
+        return (
+            "curb_cut_plane_decomposition",
+            "Decompose sidewalk, road, and sloped transition planes before meshing.",
+        )
+    if category == "raised_curb":
+        return (
+            "raised_curb_prism_fit",
+            "Fit one continuous curb top and vertical face, then extrude a solid prism without repeated stair bands.",
+        )
+    if category == "tactile_paving":
+        return (
+            "tactile_centerline_completion",
+            "Keep a narrow tactile strip, continue its centerline, and avoid expanding to the full sidewalk.",
+        )
+    if category in {"ramp", "walkway"}:
+        return (
+            "plane_fit",
+            "Fit visible support only, reject obstacle/depth outliers, and project hidden pixels to the plane.",
+        )
+    return "manual_review", "Unknown category; keep the sample out of automatic 3D completion."
+
+
+def build_accessibility_geometry_analysis(
+    *,
+    sample_id: str | None,
+    category: str | None,
+    geometry_mode: str,
+    visible_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    hidden_mask: np.ndarray,
+    obstacle_mask: np.ndarray,
+    depth: np.ndarray,
+    completed_depth: np.ndarray,
+    confidence: np.ndarray,
+    completion_method: str,
+    edges_y: list[int],
+    stair_edge_slope: float,
+    edge_source: str,
+    stair_edge_confidence: float,
+    stair_edge_coverage: float,
+    used_regular_fallback_edges: bool,
+    visible_depth_unchanged: bool,
+    completed_target_depth_finite: bool,
+    point_cloud_vertices: int,
+    mesh_vertices: int,
+    mesh_faces: int,
+) -> dict[str, Any]:
+    """Build the JSON-ready geometry constraint report."""
+
+    normalized_category = normalize_category(category, geometry_mode)
+    target_present = bool(np.any(amodal_mask) or np.any(visible_mask))
+    hidden_nonempty = bool(np.any(hidden_mask))
+    hidden_confidence_values = confidence[hidden_mask] if hidden_nonempty else np.array([1.0], dtype=np.float32)
+    mean_hidden_confidence = float(np.mean(hidden_confidence_values)) if hidden_confidence_values.size else 0.0
+    visible_area = int(visible_mask.sum())
+    amodal_area = int(amodal_mask.sum())
+    hidden_area = int(hidden_mask.sum())
+    obstacle_area = int(obstacle_mask.sum())
+    obstacle_target_overlap = int((obstacle_mask & amodal_mask).sum())
+    obstacle_visible_overlap_ratio = _ratio(int((obstacle_mask & visible_mask).sum()), max(visible_area, 1))
+
+    if normalized_category == "stairs":
+        structure_confidence = float(stair_edge_confidence)
+        if used_regular_fallback_edges:
+            structure_confidence = min(structure_confidence, 0.30)
+    elif normalized_category in CONTINUOUS_CATEGORIES:
+        structure_confidence = 0.72 if "plane" in completion_method else 0.38
+    else:
+        structure_confidence = 0.20
+
+    target_evidence_score = min(1.0, 0.25 + 0.75 * _ratio(visible_area, max(amodal_area, 1)))
+    mesh_score = 1.0 if point_cloud_vertices > 0 and mesh_vertices > 0 and mesh_faces > 0 else 0.25
+    geometry_confidence = min(
+        0.99,
+        max(
+            0.0,
+            0.35 * structure_confidence
+            + 0.25 * mean_hidden_confidence
+            + 0.20 * target_evidence_score
+            + 0.20 * mesh_score,
+        ),
+    )
+    if not target_present:
+        geometry_confidence = 0.0
+    if not completed_target_depth_finite:
+        geometry_confidence *= 0.50
+
+    amodal_quality = _amodal_quality(
+        target_present,
+        visible_mask,
+        amodal_mask,
+        hidden_mask,
+        mean_hidden_confidence,
+        used_regular_fallback_edges,
+    )
+    if amodal_quality in {"uncertain", "bad"}:
+        geometry_confidence = min(geometry_confidence, 0.55 if amodal_quality == "uncertain" else 0.20)
+
+    visible_evidence = _visible_evidence(
+        normalized_category,
+        visible_mask,
+        amodal_mask,
+        hidden_mask,
+        obstacle_mask,
+        depth,
+        edges_y,
+        stair_edge_confidence,
+        stair_edge_coverage,
+        completion_method,
+    )
+
+    occluders = []
+    if obstacle_area > 0:
+        occluders.append(
+            {
+                "class": "other",
+                "overlaps_target": bool(obstacle_target_overlap > 0),
+                "should_exclude_from_mesh": True,
+                "description": (
+                    "aggregate obstacle mask overlaps the target support"
+                    if obstacle_target_overlap > 0
+                    else "aggregate obstacle mask is outside the target support"
+                ),
+            }
+        )
+
+    hidden_regions = _connected_hidden_regions(
+        normalized_category,
+        hidden_mask,
+        completion_method,
+        mean_hidden_confidence,
+        edges_y,
+    )
+
+    plane_applies = normalized_category in CONTINUOUS_CATEGORIES
+    stair_applies = normalized_category == "stairs"
+    model_type = _geometry_model_type(normalized_category, geometry_mode)
+    slope_direction = _slope_direction_from_depth(completed_depth, amodal_mask)
+    expected_surface = (
+        "segmented"
+        if normalized_category in {"stairs", "curb_cut"}
+        else "continuous_top_with_vertical_face"
+        if normalized_category == "raised_curb"
+        else "sloped"
+        if normalized_category == "ramp"
+        else "flat"
+        if normalized_category in {"walkway", "tactile_paving"}
+        else "segmented"
+    )
+    hidden_depth_rule = _hidden_depth_rule(normalized_category, completion_method)
+    step_lines = [
+        {
+            "y": int(y),
+            "slope": _round(stair_edge_slope),
+            "source": edge_source,
+        }
+        for y in edges_y
+    ]
+
+    if normalized_category == "stairs":
+        passable = False
+        risk_level = "high" if geometry_confidence >= 0.30 else "unknown"
+        risks = ["stairs present", "wheeled passability is blocked or requires alternate route"]
+        if used_regular_fallback_edges:
+            risks.append("stair geometry relies on fallback edge positions")
+        reason_short = "Stair geometry is detected; treat as high risk for wheeled accessibility."
+    elif normalized_category == "raised_curb":
+        passable = False
+        risk_level = "high" if geometry_confidence >= 0.30 else "unknown"
+        risks = [
+            "raised curb is a non-walkable level-change barrier",
+            "wheeled passability is blocked or requires a curb cut or alternate route",
+        ]
+        reason_short = "A raised curb is present; model it as a continuous high obstacle, not as stairs."
+    elif geometry_confidence < 0.30 or amodal_quality in {"uncertain", "bad"}:
+        passable = False
+        risk_level = "unknown"
+        risks = ["hidden support geometry is uncertain"]
+        reason_short = "Evidence is insufficient for an automatic passability decision."
+    else:
+        obstacle_intrusion = _ratio(obstacle_target_overlap, max(amodal_area, 1))
+        passable = obstacle_intrusion < 0.25 and visible_depth_unchanged
+        risk_level = "medium" if hidden_nonempty or obstacle_intrusion > 0.10 else "low"
+        risks = []
+        if hidden_nonempty:
+            risks.append("hidden region may contain unresolved hazards")
+        if obstacle_intrusion > 0.10:
+            risks.append("obstacle intrudes into the target support")
+        if not risks:
+            risks.append("no major geometry risk from available masks")
+        reason_short = "Continuous support appears geometrically consistent, but monocular depth is not metric truth."
+
+    triangle_fan_passed = True
+    if normalized_category in CONTINUOUS_CATEGORIES:
+        triangle_fan_passed = bool(mesh_faces > 0 and ("plane" in completion_method or "continuous" in completion_method))
+    stair_not_smoothed_passed = True
+    if normalized_category == "stairs":
+        stair_not_smoothed_passed = bool(
+            "stair" in completion_method and len(edges_y) >= 2 and stair_edge_confidence > 0.0
+        )
+    raised_curb_not_stepped_passed = True
+    if normalized_category == "raised_curb":
+        raised_curb_not_stepped_passed = bool(
+            geometry_mode != "stairs" and "stair" not in completion_method and not edges_y
+        )
+    obstacle_exclusion_passed = obstacle_visible_overlap_ratio <= 0.02
+    hidden_follows_amodal = bool(np.array_equal(hidden_mask, amodal_mask & ~visible_mask))
+
+    next_step, instruction = _recommended_action(normalized_category, geometry_confidence)
+
+    return {
+        "sample_id": sample_id or "",
+        "category": normalized_category,
+        "target_present": target_present,
+        "geometry_confidence": _round(geometry_confidence),
+        "visible_evidence": visible_evidence,
+        "occluders": occluders,
+        "amodal_completion": {
+            "target_amodal_region_quality": amodal_quality,
+            "hidden_regions": hidden_regions,
+            "do_not_complete_regions": [
+                {
+                    "description": "obstacle mask outside the hidden target support",
+                    "reason": "foreground occluder geometry is not part of the accessible support surface",
+                },
+                {
+                    "description": "outside target_amodal mask",
+                    "reason": "completion must be clipped to reviewed or inferred target support",
+                },
+                {
+                    "description": "thin mask boundary band, shadows, reflections, and wall/railing regions",
+                    "reason": "these pixels are unstable depth or non-walkable geometry",
+                },
+            ],
+        },
+        "geometry_prior": {
+            "model_type": model_type,
+            "plane_prior": {
+                "applies": plane_applies,
+                "slope_direction_image": slope_direction,
+                "expected_surface": expected_surface,
+                "fit_visible_only_then_extend_to_hidden": True,
+                "reject_depth_outliers": True,
+            },
+            "stairs_prior": {
+                "applies": stair_applies,
+                "step_direction_image": slope_direction,
+                "visible_step_lines": step_lines,
+                "estimated_step_count": len(edges_y) + 1 if edges_y else None,
+                "step_interval_consistency": _step_interval_consistency(edges_y),
+                "hidden_completion_rule": "repeat_visible_tread_riser_pattern",
+            },
+            "curb_cut_prior": {
+                "applies": normalized_category == "curb_cut",
+                "has_sidewalk_plane": None if normalized_category != "curb_cut" else "plane" in completion_method,
+                "has_road_plane": None,
+                "has_sloped_transition": None if normalized_category != "curb_cut" else "plane" in completion_method,
+                "boundary_or_hinge_lines": [],
+            },
+            "raised_curb_prior": {
+                "applies": normalized_category == "raised_curb",
+                "is_walkable_surface": False if normalized_category == "raised_curb" else None,
+                "hazard_class": "high_obstacle" if normalized_category == "raised_curb" else None,
+                "has_continuous_top_surface": (
+                    None if normalized_category != "raised_curb" else "plane" in completion_method
+                ),
+                "vertical_face_required": True if normalized_category == "raised_curb" else None,
+                "repeated_step_profile_allowed": False if normalized_category == "raised_curb" else None,
+                "boundary_or_hinge_lines": [],
+            },
+        },
+        "depth_completion_constraints": {
+            "trusted_depth_regions": [
+                "visible target surface excluding obstacle and mask boundary noise",
+            ],
+            "untrusted_depth_regions": [
+                "obstacle mask",
+                "hidden mask raw depth",
+                "thin railings",
+                "mask boundary band",
+                "specular/shadow regions",
+            ],
+            "hidden_depth_rule": hidden_depth_rule,
+            "mesh_generation_rule": (
+                "fit one continuous curb top, add a vertical face, and forbid repeated stair bands"
+                if normalized_category == "raised_curb"
+                else "clip mesh by target_amodal mask, remove obstacle geometry, regularize hidden region"
+            ),
+        },
+        "passability_assessment": {
+            "is_likely_passable": passable,
+            "risk_level": risk_level,
+            "risks": risks,
+            "reason_short": reason_short,
+        },
+        "failure_checks": [
+            {
+                "check": "ramp_or_walkway_should_not_collapse_into_triangle_fan",
+                "passed": triangle_fan_passed,
+                "fix_if_failed": "use RANSAC plane fitting on visible target and project hidden mask to fitted plane",
+            },
+            {
+                "check": "stairs_should_not_be_smoothed_into_single_ramp",
+                "passed": stair_not_smoothed_passed,
+                "fix_if_failed": "fit repeated tread/riser geometry",
+            },
+            {
+                "check": "raised_curb_should_not_use_repeated_stair_bands",
+                "passed": raised_curb_not_stepped_passed,
+                "fix_if_failed": "switch to continuous-surface completion and fit one raised curb prism",
+            },
+            {
+                "check": "obstacles_should_not_be_included_in_accessible_mesh",
+                "passed": obstacle_exclusion_passed,
+                "fix_if_failed": "subtract obstacle mask before point cloud and mesh creation",
+            },
+            {
+                "check": "hidden_region_should_follow_amodal_mask_not_visible_mask_only",
+                "passed": hidden_follows_amodal,
+                "fix_if_failed": "use target_amodal and hidden masks as reconstruction constraints",
+            },
+        ],
+        "recommended_3d_action": {
+            "next_step": next_step,
+            "short_instruction_for_reconstruction_code": instruction,
+        },
+    }

accessibilityamodal/pipeline.py

@@ -0,0 +1,886 @@
+"""AccessibilityAmodal mask construction and geometry completion.
+
+The script is an orchestration layer. It does not vendor the external projects;
+instead it consumes their outputs or calls a running LISA Gradio server when
+available. This keeps the project-owned AccessibilityAmodal workflow separate
+from the incompatible dependency trees of LISA, Grounded-SAM, Amodal-Wild,
+Diffusion-VAS, pix2gestalt, and the optional licensed visual 3D backend.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.request import urlopen
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps
+
+from accessibilityamodal.category_overrides import (
+    DEFAULT_CATEGORY_OVERRIDES_PATH,
+    load_reviewed_category_overrides,
+    resolve_reviewed_category,
+)
+from accessibilityamodal.visual_completion import (
+    build_completion_envelope,
+    build_visual_removal_mask,
+)
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+
+
+ACCESSIBILITY_PRESETS = {
+    'stairs': {
+        'target_prompt': 'Can you segment all visible stair steps and stair walking surfaces in this image? Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment the suitcase, luggage, person, vehicle, or any object occluding the stairs in this image? Please output segmentation mask.',
+    },
+    'tactile_paving': {
+        'target_prompt': 'Can you segment the visible tactile paving or blind sidewalk guiding tiles in this image? Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment the object blocking the tactile paving path in this image? Please output segmentation mask.',
+    },
+    'ramp': {
+        'target_prompt': 'Can you segment the visible wheelchair ramp or accessible sloped walking surface in this image? Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment the object blocking the wheelchair ramp or accessible route in this image? Please output segmentation mask.',
+    },
+    'curb_cut': {
+        'target_prompt': 'Can you segment the visible curb cut ramp, sidewalk transition, and accessible sloped crossing surface in this image? Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment objects blocking the curb cut, sidewalk transition, or accessible crossing in this image? Please output segmentation mask.',
+    },
+    'raised_curb': {
+        'target_prompt': 'Can you segment the visible raised road curb, including its continuous top edge and vertical face, in this image? Exclude stairs and curb-cut ramps. Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment people, vehicles, vegetation, or other objects occluding the raised curb in this image? Please output segmentation mask.',
+    },
+    'walkway': {
+        'target_prompt': 'Can you segment the visible accessible pedestrian walkway or sidewalk support surface in this image? Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment obstacles blocking the accessible walkway or sidewalk path in this image? Please output segmentation mask.',
+    },
+    'walkable': {
+        'target_prompt': 'Can you segment the visible accessible walkable path for a wheelchair or delivery robot in this image? Please output segmentation mask.',
+        'obstacle_prompt': 'Can you segment obstacles blocking the accessible walking path in this image? Please output segmentation mask.',
+    },
+}
+
+
+def read_rgb(path: str | Path) -> np.ndarray:
+    """Read RGB in the same display orientation used by the mask proposal stage."""
+    return np.array(ImageOps.exif_transpose(Image.open(path)).convert('RGB'))
+
+
+def save_mask(path: str | Path, mask: np.ndarray) -> None:
+    Image.fromarray((mask.astype(np.uint8) * 255)).save(path)
+
+
+def read_mask(path: str | Path, shape: tuple[int, int]) -> np.ndarray:
+    mask = np.array(ImageOps.exif_transpose(Image.open(path)).convert('L')) > 127
+    h, w = shape
+    if mask.shape != (h, w):
+        raise ValueError(
+            f'Mask/RGB raster mismatch for {path}: mask={mask.shape}, rgb={(h, w)}. '
+            'Refusing to resize because it can hide EXIF-orientation misalignment.'
+        )
+    return mask
+
+
+def parse_box(text: str) -> tuple[float, float, float, float]:
+    values = tuple(float(v) for v in text.split(','))
+    if len(values) != 4:
+        raise argparse.ArgumentTypeError('box must be x1,y1,x2,y2')
+    x1, y1, x2, y2 = values
+    if x2 <= x1 or y2 <= y1:
+        raise argparse.ArgumentTypeError('box must satisfy x2>x1 and y2>y1')
+    return values
+
+
+def boxes_to_mask(boxes: list[tuple[float, float, float, float]], shape: tuple[int, int]) -> np.ndarray:
+    h, w = shape
+    mask = np.zeros(shape, dtype=bool)
+    for x1, y1, x2, y2 in boxes:
+        if max(x1, y1, x2, y2) <= 1.0:
+            x1, x2 = x1 * w, x2 * w
+            y1, y2 = y1 * h, y2 * h
+        left = int(np.clip(round(x1), 0, w - 1))
+        right = int(np.clip(round(x2), left + 1, w))
+        top = int(np.clip(round(y1), 0, h - 1))
+        bottom = int(np.clip(round(y2), top + 1, h))
+        mask[top:bottom, left:right] = True
+    return mask
+
+
+def mask_from_lisa_json(path: str | Path, shape: tuple[int, int]) -> np.ndarray:
+    with open(path, 'r', encoding='utf-8') as f:
+        data: Any = json.load(f)
+    if isinstance(data, dict) and 'data' in data:
+        data = data['data']
+    arr = np.array(data)
+    if arr.ndim == 3:
+        arr = arr[..., 0]
+    mask = arr.astype(np.float32) > 0
+    h, w = shape
+    if mask.shape != (h, w):
+        raise ValueError(
+            f'LISA mask/RGB raster mismatch for {path}: mask={mask.shape}, rgb={(h, w)}. '
+            'Refusing to resize because the LISA input must share the normalized display-oriented grid.'
+        )
+    return mask
+
+
+def lisa_server_reachable(server_url: str, timeout: float = 2.0) -> bool:
+    try:
+        with urlopen(server_url, timeout=timeout):
+            return True
+    except Exception:
+        return False
+
+
+def call_lisa(server_url: str, image_path: str, prompt: str, out_prefix: Path, shape: tuple[int, int]) -> np.ndarray:
+    try:
+        from gradio_client import Client
+    except ImportError as exc:
+        raise RuntimeError('gradio_client is not installed in this environment') from exc
+
+    client = Client(server_url)
+    result = client.predict(prompt, image_path, api_name='/predict')
+    if not isinstance(result, (tuple, list)) or len(result) < 2:
+        raise RuntimeError(f'Unexpected LISA response: {result!r}')
+
+    rendered_path = Path(result[0])
+    json_path = Path(result[1])
+    copied_rendered = out_prefix.with_suffix('.png')
+    copied_json = out_prefix.with_suffix('.json')
+    if rendered_path.exists():
+        shutil.copyfile(rendered_path, copied_rendered)
+    shutil.copyfile(json_path, copied_json)
+    return mask_from_lisa_json(copied_json, shape)
+
+
+def largest_components(mask: np.ndarray, keep: int = 3, min_area: int = 64) -> np.ndarray:
+    num, labels, stats, _ = cv2.connectedComponentsWithStats(mask.astype(np.uint8), connectivity=8)
+    if num <= 1:
+        return mask.astype(bool)
+    areas = [(idx, stats[idx, cv2.CC_STAT_AREA]) for idx in range(1, num)]
+    areas = [(idx, area) for idx, area in areas if area >= min_area]
+    areas.sort(key=lambda item: item[1], reverse=True)
+    kept = np.zeros_like(mask, dtype=bool)
+    for idx, _ in areas[:keep]:
+        kept |= labels == idx
+    return kept
+
+
+def heuristic_target_mask(rgb: np.ndarray, preset: str) -> np.ndarray:
+    h, w = rgb.shape[:2]
+    gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+    edges = cv2.Canny(cv2.GaussianBlur(gray, (5, 5), 0), 60, 160)
+    lower = np.zeros((h, w), dtype=np.uint8)
+    lower[int(0.12 * h):, :] = 1
+    if preset == 'stairs':
+        horizontal_kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (max(25, w // 18), 3))
+        horizontal = cv2.morphologyEx(edges, cv2.MORPH_CLOSE, horizontal_kernel)
+        band = cv2.dilate(horizontal, cv2.getStructuringElement(cv2.MORPH_RECT, (max(35, w // 14), max(9, h // 80))))
+        mask = (band > 0) & (lower > 0)
+        if mask.sum() < 0.03 * h * w:
+            mask = lower.astype(bool)
+        return mask
+    return lower.astype(bool)
+
+
+def heuristic_obstacle_mask(rgb: np.ndarray, boxes: list[tuple[float, float, float, float]], target_mask: np.ndarray) -> np.ndarray:
+    h, w = target_mask.shape
+    if boxes:
+        return boxes_to_mask(boxes, (h, w))
+    # Conservative central occluder prior for one-off experiments. It is not a
+    # replacement for a real LISA/Grounded-SAM obstacle mask.
+    return boxes_to_mask([(0.36, 0.32, 0.68, 0.88)], (h, w)) & cv2.dilate(
+        target_mask.astype(np.uint8),
+        cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (max(31, w // 24), max(31, h // 24))),
+    ).astype(bool)
+
+
+def row_span_amodal_mask(visible_mask: np.ndarray, obstacle_mask: np.ndarray, fallback_mask: np.ndarray) -> np.ndarray:
+    h, w = visible_mask.shape
+    rows = np.where(visible_mask.any(axis=1))[0]
+    if rows.size < 2:
+        return fallback_mask
+
+    lefts = np.full(h, np.nan, dtype=np.float32)
+    rights = np.full(h, np.nan, dtype=np.float32)
+    for y in rows:
+        xs = np.where(visible_mask[y])[0]
+        if xs.size:
+            lefts[y] = np.percentile(xs, 3)
+            rights[y] = np.percentile(xs, 97)
+
+    known = np.where(np.isfinite(lefts) & np.isfinite(rights))[0]
+    y_all = np.arange(h)
+    left_interp = np.interp(y_all, known, lefts[known])
+    right_interp = np.interp(y_all, known, rights[known])
+
+    margin = max(20, int(0.04 * w))
+    top = max(0, int(known.min() - 0.04 * h))
+    bottom = min(h, int(known.max() + 0.08 * h))
+    amodal = np.zeros((h, w), dtype=bool)
+    for y in range(top, bottom):
+        left = int(np.clip(left_interp[y] - margin, 0, w - 1))
+        right = int(np.clip(right_interp[y] + margin, left + 1, w))
+        amodal[y, left:right] = True
+
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (max(21, w // 48), max(21, h // 48)))
+    amodal = cv2.morphologyEx(amodal.astype(np.uint8), cv2.MORPH_CLOSE, kernel).astype(bool)
+    amodal |= visible_mask
+    return amodal
+
+
+def reviewed_geometry_support_prior(
+    reviewed_amodal: np.ndarray,
+    target_visible: np.ndarray,
+    obstacle_mask: np.ndarray,
+    *,
+    envelope_margin_fraction: float = 0.012,
+    maximum_hull_expansion_ratio: float = 2.0,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """Bridge reviewed occluder gaps without replacing the reviewed mask.
+
+    Accessibility annotations can be semantically correct yet retain a person-
+    shaped notch in the support surface.  Raw triangulation then preserves that
+    notch as a hole.  This helper builds a *geometry-only hypothesis*:
+
+    1. retain complete obstacle components that intersect the reviewed hidden
+       target;
+    2. form small component bounding envelopes, matching the 2D removal policy;
+    3. add only envelope pixels that lie inside a robust convex support hull.
+
+    The hull is derived from non-trivial reviewed components, so isolated mask
+    speckles cannot stretch it across the image.  Highly concave/ambiguous
+    targets fail closed and keep the reviewed mask unchanged.
+    """
+
+    amodal = np.asarray(reviewed_amodal, dtype=bool)
+    visible = np.asarray(target_visible, dtype=bool)
+    obstacle = np.asarray(obstacle_mask, dtype=bool)
+    if amodal.ndim != 2 or visible.ndim != 2 or obstacle.ndim != 2:
+        raise ValueError("reviewed amodal, visible, and obstacle masks must be 2D")
+    if amodal.shape != visible.shape or amodal.shape != obstacle.shape:
+        raise ValueError("reviewed amodal, visible, and obstacle masks must align")
+    if envelope_margin_fraction < 0:
+        raise ValueError("envelope_margin_fraction must be non-negative")
+    if maximum_hull_expansion_ratio < 1:
+        raise ValueError("maximum_hull_expansion_ratio must be at least 1")
+
+    reviewed = amodal | visible
+    hidden = reviewed & ~visible
+    visual_removal, removal_stats = build_visual_removal_mask(hidden, obstacle)
+    completion_envelope, envelope_stats = build_completion_envelope(
+        visual_removal,
+        obstacle,
+        margin_fraction=envelope_margin_fraction,
+    )
+
+    reviewed_pixels = int(reviewed.sum())
+    base_metadata: dict[str, Any] = {
+        "policy": (
+            "reviewed_mask_plus_occluder_envelope_inside_robust_convex_support_hull"
+        ),
+        "reviewed_pixel_count": reviewed_pixels,
+        "reviewed_hidden_pixel_count": int(hidden.sum()),
+        "visual_removal_pixel_count": int(visual_removal.sum()),
+        "completion_envelope_pixel_count": int(completion_envelope.sum()),
+        "envelope_margin_fraction": float(envelope_margin_fraction),
+        "maximum_hull_expansion_ratio": float(maximum_hull_expansion_ratio),
+        "obstacle_components_retained": int(
+            removal_stats["obstacle_components_retained"]
+        ),
+        "envelope_component_count": int(envelope_stats["component_count"]),
+    }
+    if reviewed_pixels == 0:
+        return reviewed.copy(), {
+            **base_metadata,
+            "status": "unchanged_empty_reviewed_mask",
+            "hull_source_pixel_count": 0,
+            "hull_pixel_count": 0,
+            "hull_expansion_ratio": None,
+            "added_support_pixel_count": 0,
+        }
+
+    count, labels, component_stats, _ = cv2.connectedComponentsWithStats(
+        reviewed.astype(np.uint8),
+        connectivity=8,
+    )
+    minimum_component_area = max(32, int(round(reviewed_pixels * 0.002)))
+    hull_source = np.zeros_like(reviewed)
+    retained_component_count = 0
+    for label in range(1, count):
+        area = int(component_stats[label, cv2.CC_STAT_AREA])
+        if area >= minimum_component_area:
+            hull_source |= labels == label
+            retained_component_count += 1
+    if not hull_source.any():
+        hull_source = reviewed.copy()
+        retained_component_count = max(0, count - 1)
+
+    ys, xs = np.where(hull_source)
+    points = np.column_stack([xs, ys]).astype(np.int32)
+    hull = np.zeros_like(reviewed, dtype=np.uint8)
+    if points.shape[0] >= 3:
+        cv2.fillConvexPoly(hull, cv2.convexHull(points), 1)
+    else:
+        hull[hull_source] = 1
+    hull_mask = hull.astype(bool)
+    hull_source_pixels = int(hull_source.sum())
+    hull_pixels = int(hull_mask.sum())
+    hull_ratio = hull_pixels / max(hull_source_pixels, 1)
+
+    metadata = {
+        **base_metadata,
+        "minimum_hull_component_area": minimum_component_area,
+        "hull_source_component_count": retained_component_count,
+        "hull_source_pixel_count": hull_source_pixels,
+        "hull_source_fraction_of_reviewed": round(
+            hull_source_pixels / reviewed_pixels,
+            8,
+        ),
+        "hull_pixel_count": hull_pixels,
+        "hull_expansion_ratio": round(hull_ratio, 8),
+    }
+    if hull_ratio > maximum_hull_expansion_ratio:
+        return reviewed.copy(), {
+            **metadata,
+            "status": "unchanged_ambiguous_hull_expansion",
+            "added_support_pixel_count": 0,
+        }
+
+    added_support = completion_envelope & hull_mask & ~reviewed
+    support_prior = reviewed | added_support
+    return support_prior, {
+        **metadata,
+        "status": (
+            "augmented_occluded_support_hypothesis"
+            if added_support.any()
+            else "unchanged_no_supported_gap"
+        ),
+        "added_support_pixel_count": int(added_support.sum()),
+        "support_prior_pixel_count": int(support_prior.sum()),
+        "support_prior_is_metric_truth": False,
+        "human_review_required": True,
+    }
+
+
+def maybe_refine_masks_with_sam(
+    args,
+    rgb: np.ndarray,
+    target_visible: np.ndarray,
+    obstacle: np.ndarray,
+    output_dir: Path,
+) -> tuple[np.ndarray, np.ndarray, str | None]:
+    if not args.sam_refine:
+        return target_visible, obstacle, None
+    if not args.sam_checkpoint:
+        message = 'SAM refinement requested but --sam-checkpoint was not provided'
+        if args.sam_fallback == 'error':
+            raise ValueError(message)
+        print(f'{message}; keeping coarse masks', file=sys.stderr)
+        return target_visible, obstacle, message
+
+    pre_target = output_dir / 'pre_sam_target_visible_mask.png'
+    pre_obstacle = output_dir / 'pre_sam_obstacle_mask.png'
+    save_mask(pre_target, target_visible)
+    save_mask(pre_obstacle, obstacle)
+
+    sam_output_dir = output_dir / 'sam_refine'
+    cmd = [
+        sys.executable,
+        '-m',
+        'accessibilityamodal.sam_refinement',
+        '--image', args.image,
+        '--target-mask', str(pre_target),
+        '--obstacle-mask', str(pre_obstacle),
+        '--output-dir', str(sam_output_dir),
+        '--sam-repo', args.sam_repo,
+        '--sam-checkpoint', args.sam_checkpoint,
+        '--sam-model-type', args.sam_model_type,
+        '--device', args.sam_device,
+        '--keep-target-components', str(args.keep_target_components),
+        '--keep-obstacle-components', str(args.keep_obstacle_components),
+    ]
+    print('Running:', ' '.join(cmd))
+    try:
+        subprocess.run(cmd, check=True)
+    except Exception as exc:
+        if args.sam_fallback == 'error':
+            raise
+        message = f'SAM refinement failed; keeping coarse masks: {exc}'
+        print(message, file=sys.stderr)
+        return target_visible, obstacle, message
+
+    refined_target = read_mask(sam_output_dir / 'target_visible_mask_sam.png', rgb.shape[:2])
+    refined_obstacle = read_mask(sam_output_dir / 'obstacle_mask_sam.png', rgb.shape[:2])
+    return refined_target, refined_obstacle, f'SAM: {args.sam_model_type}'
+
+
+def write_three_value_mask(
+    path: Path, target_visible: np.ndarray, amodal_mask: np.ndarray
+) -> None:
+    mask = np.full(amodal_mask.shape, 255, dtype=np.uint8)
+    hidden = amodal_mask & ~target_visible
+    mask[target_visible] = 188
+    mask[hidden] = 0
+    Image.fromarray(mask).save(path)
+
+
+def overlay(rgb: np.ndarray, masks: list[tuple[np.ndarray, tuple[int, int, int], float]]) -> np.ndarray:
+    out = rgb.astype(np.float32).copy()
+    for mask, color, alpha in masks:
+        if mask.any():
+            out[mask] = out[mask] * (1.0 - alpha) + np.array(color, dtype=np.float32) * alpha
+    return np.clip(out, 0, 255).astype(np.uint8)
+
+
+def build_masks(args) -> dict[str, Path]:
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    rgb = read_rgb(args.image)
+    shape = rgb.shape[:2]
+    preset = ACCESSIBILITY_PRESETS[args.preset]
+    target_prompt = args.target_prompt or preset['target_prompt']
+    obstacle_prompt = args.obstacle_prompt or preset['obstacle_prompt']
+    lisa_image_path = output_dir / 'lisa_input_display_oriented.png'
+    if args.use_lisa:
+        Image.fromarray(rgb).save(lisa_image_path)
+
+    if args.target_visible_mask:
+        target_visible = read_mask(args.target_visible_mask, shape)
+        target_source = args.target_visible_mask
+    elif args.use_lisa and lisa_server_reachable(args.lisa_server_url):
+        target_visible = call_lisa(args.lisa_server_url, str(lisa_image_path), target_prompt, output_dir / 'lisa_target_visible', shape)
+        target_source = f'LISA: {target_prompt}'
+    else:
+        if args.use_lisa and args.lisa_fallback == 'error':
+            raise RuntimeError(f'LISA server is not reachable: {args.lisa_server_url}')
+        target_visible = heuristic_target_mask(rgb, args.preset)
+        target_source = 'heuristic target mask'
+
+    if not args.target_visible_mask:
+        target_visible = largest_components(
+            target_visible,
+            keep=args.keep_target_components,
+            min_area=max(64, shape[0] * shape[1] // 20000),
+        )
+
+    if args.obstacle_mask:
+        obstacle = read_mask(args.obstacle_mask, shape)
+        obstacle_source = args.obstacle_mask
+    elif args.use_lisa and lisa_server_reachable(args.lisa_server_url):
+        try:
+            obstacle = call_lisa(args.lisa_server_url, str(lisa_image_path), obstacle_prompt, output_dir / 'lisa_obstacle', shape)
+            obstacle_source = f'LISA: {obstacle_prompt}'
+        except Exception as exc:
+            if args.lisa_fallback == 'error':
+                raise
+            print(f'LISA obstacle segmentation failed, falling back to heuristic obstacle mask: {exc}', file=sys.stderr)
+            obstacle = heuristic_obstacle_mask(rgb, args.occlusion_box, target_visible)
+            obstacle_source = 'heuristic obstacle mask after LISA failure'
+    else:
+        if args.use_lisa and args.lisa_fallback == 'error':
+            raise RuntimeError(f'LISA server is not reachable: {args.lisa_server_url}')
+        obstacle = heuristic_obstacle_mask(rgb, args.occlusion_box, target_visible)
+        obstacle_source = 'heuristic obstacle mask'
+
+    if not args.obstacle_mask:
+        obstacle = largest_components(
+            obstacle,
+            keep=args.keep_obstacle_components,
+            min_area=max(64, shape[0] * shape[1] // 30000),
+        )
+    target_visible, obstacle, sam_source = maybe_refine_masks_with_sam(args, rgb, target_visible, obstacle, output_dir)
+    if sam_source:
+        target_source = f'{target_source} + {sam_source}'
+        obstacle_source = f'{obstacle_source} + {sam_source}'
+    # Occluders are never part of the support surface. This guard also fixes
+    # broad heuristic/LISA target masks that accidentally include a person,
+    # vehicle, railing, or clutter region.
+    target_visible &= ~obstacle
+
+    if args.target_amodal_mask:
+        provided_amodal = read_mask(args.target_amodal_mask, shape)
+        reviewed_amodal = provided_amodal | target_visible
+        amodal_support_prior, support_prior_metadata = (
+            reviewed_geometry_support_prior(
+                reviewed_amodal,
+                target_visible,
+                obstacle,
+            )
+        )
+        amodal = amodal_support_prior.copy()
+        hidden = amodal_support_prior & ~target_visible
+        amodal_source = args.target_amodal_mask
+        completion_policy = (
+            "reviewed target mask plus auditable occluder-constrained "
+            "geometry support hypothesis"
+        )
+    else:
+        fallback_target = heuristic_target_mask(rgb, args.preset)
+        # Row-span completion is only a structural support prior. Restrict hidden
+        # completion to observed obstacle pixels so disjoint stairs/walkways are not
+        # connected across unoccluded image regions.
+        amodal_support_prior = row_span_amodal_mask(
+            target_visible, obstacle, fallback_target
+        )
+        hidden = obstacle & amodal_support_prior & ~target_visible
+        amodal = target_visible | hidden
+        reviewed_amodal = amodal.copy()
+        amodal_source = "obstacle-constrained perspective baseline"
+        completion_policy = "obstacle-constrained row-span structural support prior"
+        support_prior_metadata = {
+            "policy": completion_policy,
+            "status": "heuristic_obstacle_constrained_support_prior",
+            "reviewed_pixel_count": int(amodal.sum()),
+            "added_support_pixel_count": 0,
+            "support_prior_pixel_count": int(amodal_support_prior.sum()),
+            "support_prior_is_metric_truth": False,
+            "human_review_required": True,
+        }
+
+    visual_3d_hidden = reviewed_amodal & ~target_visible
+    paths = {
+        'target_visible': output_dir / 'target_visible_mask.png',
+        'obstacle': output_dir / 'obstacle_mask.png',
+        'amodal': output_dir / 'amodal_accessibility_mask.png',
+        'reviewed_amodal': output_dir / 'reviewed_amodal_source_mask.png',
+        'hidden': output_dir / 'hidden_completion_mask.png',
+        'support_prior': output_dir / 'amodal_support_prior.png',
+        'visual_3d_condition': output_dir / 'amodal3d_three_value_mask.png',
+        'visual_3d_condition_compatibility': (
+            output_dir / 'accessibilityamodal_condition_mask.png'
+        ),
+        'overlay': output_dir / 'mask_debug_overlay.png',
+        'manifest': output_dir / 'mask_manifest.json',
+    }
+    save_mask(paths['target_visible'], target_visible)
+    save_mask(paths['obstacle'], obstacle)
+    save_mask(paths['amodal'], amodal)
+    save_mask(paths['reviewed_amodal'], reviewed_amodal)
+    save_mask(paths['hidden'], hidden)
+    save_mask(paths['support_prior'], amodal_support_prior)
+    # Visual Accessibility3D conditioning must reflect only the reviewed support.
+    # The expanded support prior remains a geometry-only hypothesis consumed by
+    # reconstruct_steps and must not leak into the visual three-value mask.
+    write_three_value_mask(
+        paths['visual_3d_condition'],
+        target_visible,
+        reviewed_amodal,
+    )
+    shutil.copyfile(
+        paths['visual_3d_condition'],
+        paths['visual_3d_condition_compatibility'],
+    )
+    debug = overlay(rgb, [
+        (amodal, (0, 150, 255), 0.30),
+        (target_visible, (0, 220, 80), 0.45),
+        (hidden, (255, 40, 40), 0.65),
+    ])
+    Image.fromarray(debug).save(paths['overlay'])
+
+    manifest = {
+        'sample_id': args.sample_id,
+        'image': args.image,
+        'preset': args.preset,
+        'source_preset': getattr(args, 'source_preset', args.preset),
+        'category_override_applied': getattr(args, 'category_override_applied', False),
+        'category': 'walkway' if args.preset == 'walkable' else args.preset,
+        'target_prompt': target_prompt,
+        'obstacle_prompt': obstacle_prompt,
+        'target_source': target_source,
+        'obstacle_source': obstacle_source,
+        'amodal_source': amodal_source,
+        'completion_policy': completion_policy,
+        'target_visible_pixel_count': int(target_visible.sum()),
+        'obstacle_pixel_count': int(obstacle.sum()),
+        'target_obstacle_overlap_pixel_count': int((target_visible & obstacle).sum()),
+        'reviewed_amodal_pixel_count': int(reviewed_amodal.sum()),
+        'reviewed_hidden_pixel_count': int(visual_3d_hidden.sum()),
+        'geometry_support_amodal_pixel_count': int(amodal.sum()),
+        'geometry_support_hidden_pixel_count': int(hidden.sum()),
+        # Compatibility counts retained for existing manifest consumers.
+        'hidden_pixel_count': int(hidden.sum()),
+        'amodal_pixel_count': int(amodal.sum()),
+        'geometry_support_prior': support_prior_metadata,
+        'mask_roles': {
+            'visual_3d_condition': {
+                'path': str(paths['visual_3d_condition']),
+                'compatibility_path': str(
+                    paths['visual_3d_condition_compatibility']
+                ),
+                'role': 'strict_reviewed_amodal_condition_for_amodal3d',
+                'source_mask': 'reviewed_amodal',
+                'uses_geometry_support_prior': False,
+                'pixel_values': {
+                    'background': 255,
+                    'visible_target': 188,
+                    'hidden_target': 0,
+                },
+                'amodal_pixel_count': int(reviewed_amodal.sum()),
+                'hidden_pixel_count': int(visual_3d_hidden.sum()),
+            },
+            'geometry_support_prior': {
+                'path': str(paths['support_prior']),
+                'role': 'geometry_only_support_hypothesis',
+                'source_mask': 'reviewed_amodal',
+                'added_pixel_count': int(
+                    (amodal_support_prior & ~reviewed_amodal).sum()
+                ),
+                'amodal_pixel_count': int(amodal_support_prior.sum()),
+                'hidden_pixel_count': int(
+                    (amodal_support_prior & ~target_visible).sum()
+                ),
+            },
+            'reconstruct_steps_amodal_input': {
+                'path': str(paths['amodal']),
+                'role': 'geometry_support_input_for_reconstruct_steps',
+                'source_mask': 'amodal_support_prior',
+                'uses_geometry_support_prior': True,
+            },
+        },
+        'outputs': {key: str(value) for key, value in paths.items() if key != 'manifest'},
+        'external_repos_reviewed': {
+            'amodal': 'external backend; path supplied by user',
+            'Amodal-Wild': 'external backend; path supplied by user',
+            'diffusion-vas': 'external backend; path supplied by user',
+            'pix2gestalt': 'external backend; path supplied by user',
+        },
+    }
+    paths['manifest'].write_text(json.dumps(manifest, indent=2, ensure_ascii=False), encoding='utf-8')
+    return paths
+
+
+def prepare_depth(args) -> tuple[str | None, float, str]:
+    if args.depth:
+        return args.depth, args.depth_scale, f'user depth: {args.depth}'
+    if not args.estimate_depth:
+        synthetic_kind = (
+            'synthetic perspective stair prior'
+            if args.preset == 'stairs'
+            else 'synthetic continuous perspective prior'
+        )
+        return None, args.depth_scale, synthetic_kind
+
+    output_dir = Path(args.output_dir)
+    depth_path = output_dir / 'estimated_depth.npy'
+    depth_vis_path = output_dir / 'estimated_depth_vis.png'
+    depth_manifest_path = output_dir / 'depth_manifest.json'
+    cmd = [
+        sys.executable,
+        '-m',
+        'accessibilityamodal.depth',
+        '--image', args.image,
+        '--output-depth', str(depth_path),
+        '--output-vis', str(depth_vis_path),
+        '--manifest', str(depth_manifest_path),
+        '--engine', args.depth_engine,
+        '--near', str(args.depth_near),
+        '--far', str(args.depth_far),
+        '--max-size', str(args.depth_max_size),
+    ]
+    if args.depth_engine == 'transformers':
+        cmd.extend(['--model', args.depth_model, '--device', args.depth_device])
+    elif args.depth_engine == 'depth_anything_v2':
+        cmd.extend([
+            '--device', args.depth_device,
+            '--depth-anything-repo', args.depth_anything_repo,
+            '--encoder', args.depth_encoder,
+            '--input-size', str(args.depth_input_size),
+        ])
+        if args.depth_checkpoint:
+            cmd.extend(['--checkpoint', args.depth_checkpoint])
+        if args.metric_depth:
+            cmd.extend(['--metric-depth', '--max-depth', str(args.max_depth)])
+    elif args.depth_engine == 'vggt':
+        cmd.extend([
+            '--device', args.depth_device,
+            '--vggt-repo', args.vggt_repo,
+            '--vggt-model', args.vggt_model,
+            '--vggt-input-size', str(args.vggt_input_size),
+            '--output-conf', str(output_dir / 'vggt_depth_conf.npy'),
+            '--output-conf-vis', str(output_dir / 'vggt_depth_conf.png'),
+            '--output-raw-depth', str(output_dir / 'vggt_raw_depth.npy'),
+            '--output-world-points', str(output_dir / 'vggt_world_points.npy'),
+            '--output-point-conf', str(output_dir / 'vggt_world_points_conf.npy'),
+            '--output-point-cloud', str(output_dir / 'vggt_point_cloud.ply'),
+            '--point-conf-threshold', str(args.vggt_point_conf_threshold),
+            '--max-point-cloud-points', str(args.vggt_max_point_cloud_points),
+        ])
+        if args.vggt_checkpoint:
+            cmd.extend(['--vggt-checkpoint', args.vggt_checkpoint])
+        if args.vggt_keep_raw_depth:
+            cmd.append('--vggt-keep-raw-depth')
+    if args.invert_depth:
+        cmd.append('--invert-depth')
+
+    print('Running:', ' '.join(cmd))
+    try:
+        subprocess.run(cmd, check=True)
+    except Exception as exc:
+        if args.depth_fallback == 'error':
+            raise
+        print(f'Depth estimation failed, falling back to reconstruct_steps synthetic depth: {exc}', file=sys.stderr)
+        return None, args.depth_scale, f'depth estimation failed; synthetic fallback: {exc}'
+    depth_kind = f'estimated depth: {args.depth_engine}'
+    if args.metric_depth:
+        depth_kind += ' metric'
+    return str(depth_path), 1.0, depth_kind
+
+
+def run_reconstruct(args, masks: dict[str, Path], depth_path: str | None, depth_scale: float) -> None:
+    if args.skip_reconstruct:
+        return
+    category = 'walkway' if args.preset == 'walkable' else args.preset
+    geometry_mode = (
+        'stairs' if args.preset == 'stairs'
+        else 'ramp' if args.preset == 'ramp'
+        else 'walkable'
+    )
+    cmd = [
+        sys.executable,
+        '-m',
+        'accessibilityamodal.reconstruct',
+        '--image', args.image,
+        '--obstacle-mask', str(masks['obstacle']),
+        '--amodal-mask', str(masks['amodal']),
+        '--visible-mask', str(masks['target_visible']),
+        '--geometry-mode', geometry_mode,
+        '--category', category,
+        '--output-dir', str(Path(args.output_dir) / 'geometry'),
+    ]
+    if args.sample_id:
+        cmd.extend(['--sample-id', args.sample_id])
+    if args.reference_image:
+        cmd.extend(['--reference-image', args.reference_image])
+    completed_rgb = getattr(args, 'completed_rgb', None)
+    if completed_rgb:
+        cmd.extend(['--completed-rgb', completed_rgb])
+    if depth_path:
+        cmd.extend(['--depth', depth_path, '--depth-scale', str(depth_scale)])
+    if args.fx is not None:
+        cmd.extend(['--fx', str(args.fx)])
+    if args.fy is not None:
+        cmd.extend(['--fy', str(args.fy)])
+    if args.cx is not None:
+        cmd.extend(['--cx', str(args.cx)])
+    if args.cy is not None:
+        cmd.extend(['--cy', str(args.cy)])
+    print('Running:', ' '.join(cmd))
+    subprocess.run(cmd, check=True)
+
+
+def write_pipeline_manifest(args, masks: dict[str, Path], depth_source: str, depth_path: str | None) -> None:
+    output_dir = Path(args.output_dir)
+    manifest = {
+        'sample_id': args.sample_id,
+        'image': args.image,
+        'reference_image': args.reference_image,
+        'completed_rgb': args.completed_rgb,
+        'preset': args.preset,
+        'source_preset': getattr(args, 'source_preset', args.preset),
+        'category_override_applied': getattr(args, 'category_override_applied', False),
+        'category': 'walkway' if args.preset == 'walkable' else args.preset,
+        'use_lisa': args.use_lisa,
+        'lisa_server_url': args.lisa_server_url if args.use_lisa else None,
+        'depth_source': depth_source,
+        'depth_path': depth_path,
+        'reconstruct_output_dir': None if args.skip_reconstruct else str(output_dir / 'geometry'),
+        'mask_outputs': {key: str(value) for key, value in masks.items()},
+        'note': 'Depth from monocular/heuristic sources is relative unless calibrated metric depth is provided.',
+    }
+    (output_dir / 'pipeline_manifest.json').write_text(json.dumps(manifest, indent=2, ensure_ascii=False), encoding='utf-8')
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description='Build accessibility masks from text prompts and run 3D geometry completion.')
+    parser.add_argument('--image', default='./3R/2.jpg')
+    parser.add_argument('--sample-id', default=None)
+    parser.add_argument('--reference-image', default=None)
+    parser.add_argument(
+        '--completed-rgb',
+        default=None,
+        help='Aligned 2D completion used only to texture the reviewed hidden target region.',
+    )
+    parser.add_argument('--preset', choices=sorted(ACCESSIBILITY_PRESETS), default='stairs')
+    parser.add_argument(
+        '--category-overrides',
+        default=str(DEFAULT_CATEGORY_OVERRIDES_PATH),
+        help='Human-reviewed sample category overrides.',
+    )
+    parser.add_argument('--target-prompt', default=None)
+    parser.add_argument('--obstacle-prompt', default=None)
+    parser.add_argument('--target-visible-mask', default=None, help='Use an existing visible target mask instead of LISA/heuristic.')
+    parser.add_argument('--target-amodal-mask', default=None, help='Use a reviewed amodal target mask and bypass automatic mask completion.')
+    parser.add_argument('--obstacle-mask', default=None, help='Use an existing obstacle mask instead of LISA/heuristic.')
+    parser.add_argument('--occlusion-box', action='append', type=parse_box, default=[], help='Fallback obstacle box, normalized or pixel x1,y1,x2,y2.')
+    parser.add_argument('--use-lisa', action='store_true', help='Call a running LISA Gradio server for text-guided masks.')
+    parser.add_argument('--lisa-server-url', default='http://127.0.0.1:7860/')
+    parser.add_argument('--lisa-fallback', choices=['heuristic', 'error'], default='heuristic', help='What to do when a requested LISA mask cannot be obtained.')
+    parser.add_argument('--output-dir', default='./output/accessibility_pipeline/')
+    parser.add_argument('--keep-target-components', type=int, default=6)
+    parser.add_argument('--keep-obstacle-components', type=int, default=4)
+    parser.add_argument('--depth', default=None)
+    parser.add_argument('--depth-scale', type=float, default=1.0)
+    parser.add_argument('--estimate-depth', action='store_true', help='Generate a local relative depth map before reconstruction.')
+    parser.add_argument('--depth-engine', choices=['heuristic', 'transformers', 'depth_anything_v2', 'vggt'], default='heuristic', help='Local depth generator used with --estimate-depth.')
+    parser.add_argument('--depth-model', default='depth-anything/Depth-Anything-V2-Small-hf', help='Transformers depth model id or local path.')
+    parser.add_argument('--depth-device', default='auto', help='auto, cpu, cuda, cuda:0, or a transformers device string.')
+    parser.add_argument('--depth-anything-repo', default='../diffusion-vas/models/Depth_Anything_V2')
+    parser.add_argument('--depth-checkpoint', default=None, help='Local Depth Anything V2 .pth checkpoint.')
+    parser.add_argument('--depth-encoder', choices=['vits', 'vitb', 'vitl', 'vitg'], default='vitl')
+    parser.add_argument('--metric-depth', action='store_true', help='Use a metric Depth Anything V2 checkpoint and keep metric units.')
+    parser.add_argument('--max-depth', type=float, default=20.0, help='Metric depth max range in meters.')
+    parser.add_argument('--depth-input-size', type=int, default=518, help='Depth Anything V2 inference input size.')
+    parser.add_argument('--vggt-repo', default='vggt', help='Local facebookresearch/VGGT checkout.')
+    parser.add_argument('--vggt-model', default='facebook/VGGT-1B', help='Hugging Face model id or local VGGT model directory.')
+    parser.add_argument('--vggt-checkpoint', default=None, help='Optional local VGGT model.pt checkpoint.')
+    parser.add_argument('--vggt-input-size', type=int, default=518)
+    parser.add_argument('--vggt-keep-raw-depth', action='store_true', help='Do not near/far normalize VGGT depth before reconstruction.')
+    parser.add_argument('--vggt-point-conf-threshold', type=float, default=1.0)
+    parser.add_argument('--vggt-max-point-cloud-points', type=int, default=120000)
+    parser.add_argument('--depth-near', type=float, default=1.0)
+    parser.add_argument('--depth-far', type=float, default=6.0)
+    parser.add_argument('--depth-max-size', type=int, default=1280, help='Resize longest side for local depth generation. Use 0 to keep original size.')
+    parser.add_argument('--invert-depth', action='store_true', help='Invert estimated relative depth before normalization.')
+    parser.add_argument('--depth-fallback', choices=['synthetic', 'error'], default='synthetic', help='What to do if --estimate-depth fails.')
+    parser.add_argument('--fx', type=float, default=None)
+    parser.add_argument('--fy', type=float, default=None)
+    parser.add_argument('--cx', type=float, default=None)
+    parser.add_argument('--cy', type=float, default=None)
+    parser.add_argument('--sam-refine', action='store_true', help='Refine target/obstacle masks with Segment Anything box prompts.')
+    parser.add_argument('--sam-repo', default='../amodal/segment-anything')
+    parser.add_argument('--sam-checkpoint', default=None)
+    parser.add_argument('--sam-model-type', choices=['vit_h', 'vit_l', 'vit_b', 'default'], default='vit_h')
+    parser.add_argument('--sam-device', default='auto')
+    parser.add_argument('--sam-fallback', choices=['coarse', 'error'], default='coarse')
+    parser.add_argument('--skip-reconstruct', action='store_true')
+    return parser
+
+
+def main():
+    args = build_parser().parse_args()
+    args.source_preset = args.preset
+    args.preset = resolve_reviewed_category(
+        args.sample_id or '',
+        args.preset,
+        load_reviewed_category_overrides(args.category_overrides),
+    )
+    if args.preset not in ACCESSIBILITY_PRESETS:
+        raise ValueError(f'Unsupported reviewed category override: {args.preset}')
+    args.category_override_applied = args.preset != args.source_preset
+    masks = build_masks(args)
+    depth_path, depth_scale, depth_source = prepare_depth(args)
+    write_pipeline_manifest(args, masks, depth_source, depth_path)
+    run_reconstruct(args, masks, depth_path, depth_scale)
+    print(f'Wrote mask outputs to {args.output_dir}')
+
+
+if __name__ == '__main__':
+    main()

accessibilityamodal/reconstruct.py

@@ -0,0 +1,1641 @@
+"""Category-aware geometry-first depth completion for accessibility surfaces.
+
+This script is intentionally separate from inference.py. Accessibility3D is a learned
+single-object generator; stair/ramp/sidewalk completion needs explicit scene
+geometry. The pipeline here is:
+
+1. Load RGB image plus optional obstacle mask, amodal stair mask, and depth map.
+2. Use stair bands only for stairs; fit a continuous surface for walkways and
+   ramps.
+3. Extrapolate visible target depth only into the reviewed hidden region.
+4. Export completed depth, confidence, point cloud, mesh, and debug overlays.
+
+Mask convention:
+- obstacle mask: white/nonzero marks the object hiding the stair.
+- amodal mask: white/nonzero marks the whole stair/ramp target region, including
+  the occluded part.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from typing import Iterable
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps
+
+from accessibilityamodal.geometry_analysis import build_accessibility_geometry_analysis
+
+
+DEFAULT_OBSTACLE_BOX = (0.36, 0.32, 0.68, 0.88)
+
+
+def parse_box(text: str) -> tuple[float, float, float, float]:
+    values = tuple(float(v) for v in text.split(','))
+    if len(values) != 4:
+        raise argparse.ArgumentTypeError('box must be x1,y1,x2,y2')
+    x1, y1, x2, y2 = values
+    if x2 <= x1 or y2 <= y1:
+        raise argparse.ArgumentTypeError('box must satisfy x2>x1 and y2>y1')
+    return values
+
+
+def read_rgb(path: str | Path, max_size: int | None = None) -> np.ndarray:
+    image = ImageOps.exif_transpose(Image.open(path)).convert('RGB')
+    if max_size and max(image.size) > max_size:
+        scale = max_size / max(image.size)
+        new_size = (round(image.size[0] * scale), round(image.size[1] * scale))
+        image = image.resize(new_size, Image.Resampling.LANCZOS)
+    return np.array(image)
+
+
+def display_shape(path: str | Path) -> tuple[int, int]:
+    """Return the canonical EXIF-normalized source HxW without resampling it."""
+    image = ImageOps.exif_transpose(Image.open(path)).convert('RGB')
+    return image.height, image.width
+
+
+def _aspect_ratio_matches(source_shape: tuple[int, int], target_shape: tuple[int, int]) -> bool:
+    source_h, source_w = source_shape
+    target_h, target_w = target_shape
+    return abs(source_w * target_h - target_w * source_h) <= max(source_w, target_w)
+
+
+def resize_mask(mask: np.ndarray, shape: tuple[int, int]) -> np.ndarray:
+    h, w = shape
+    if mask.shape[:2] != (h, w):
+        if not _aspect_ratio_matches(mask.shape[:2], (h, w)):
+            raise ValueError(
+                f'Mask/RGB raster mismatch: mask={mask.shape[:2]}, rgb={(h, w)}. '
+                'Refusing to resize across incompatible aspect ratios because this usually indicates EXIF-orientation misalignment.'
+            )
+        mask = cv2.resize(mask.astype(np.uint8), (w, h), interpolation=cv2.INTER_NEAREST)
+    return mask > 0
+
+
+def read_mask(path: str | Path, shape: tuple[int, int]) -> np.ndarray:
+    mask = np.array(ImageOps.exif_transpose(Image.open(path)).convert('L'))
+    return resize_mask(mask > 127, shape)
+
+
+def read_source_grid_mask(
+    path: str | Path,
+    source_shape: tuple[int, int],
+    geometry_shape: tuple[int, int],
+) -> np.ndarray:
+    """Read a source-grid mask, then perform the one known shared downscale.
+
+    The normal pipeline creates target/obstacle masks on the normalized source
+    RGB grid.  Requiring that exact grid here prevents a stale same-aspect mask
+    from being silently accepted merely because it can be resized.
+    """
+    mask = np.array(ImageOps.exif_transpose(Image.open(path)).convert('L')) > 127
+    if mask.shape != source_shape:
+        raise ValueError(
+            f'Source-grid mask mismatch for {path}: mask={mask.shape}, source_rgb={source_shape}. '
+            'Expected a mask drawn on the canonical EXIF-normalized source grid before geometry downscaling.'
+        )
+    return resize_mask(mask, geometry_shape)
+
+
+def read_source_grid_rgb(
+    path: str | Path,
+    source_shape: tuple[int, int],
+    geometry_shape: tuple[int, int],
+) -> np.ndarray:
+    """Read an RGB completion on the exact source grid, then downscale once.
+
+    A generated completion is allowed to provide texture only when it is
+    aligned with the canonical, EXIF-normalized source image.  This avoids
+    silently painting a mesh from a stale or rotated completion.
+    """
+    image = ImageOps.exif_transpose(Image.open(path)).convert('RGB')
+    if (image.height, image.width) != source_shape:
+        raise ValueError(
+            f'Source-grid completed RGB mismatch for {path}: '
+            f'completed_rgb={(image.height, image.width)}, source_rgb={source_shape}. '
+            'Expected a completion on the canonical EXIF-normalized source grid.'
+        )
+    target_h, target_w = geometry_shape
+    if image.size != (target_w, target_h):
+        image = image.resize((target_w, target_h), Image.Resampling.LANCZOS)
+    return np.asarray(image)
+
+
+def boxes_to_mask(boxes: Iterable[tuple[float, float, float, float]], shape: tuple[int, int]) -> np.ndarray:
+    h, w = shape
+    mask = np.zeros((h, w), dtype=bool)
+    for x1, y1, x2, y2 in boxes:
+        if max(x1, y1, x2, y2) <= 1.0:
+            left, top, right, bottom = x1 * w, y1 * h, x2 * w, y2 * h
+        else:
+            left, top, right, bottom = x1, y1, x2, y2
+        left = int(np.clip(round(left), 0, w - 1))
+        right = int(np.clip(round(right), left + 1, w))
+        top = int(np.clip(round(top), 0, h - 1))
+        bottom = int(np.clip(round(bottom), top + 1, h))
+        mask[top:bottom, left:right] = True
+    return mask
+
+
+def default_amodal_mask(shape: tuple[int, int]) -> np.ndarray:
+    h, w = shape
+    mask = np.zeros((h, w), dtype=bool)
+    top = int(h * 0.08)
+    mask[top:, :] = True
+    return mask
+
+
+def save_mask(path: Path, mask: np.ndarray) -> None:
+    Image.fromarray((mask.astype(np.uint8) * 255)).save(path)
+
+
+def visualize_depth(depth: np.ndarray, valid: np.ndarray) -> np.ndarray:
+    vis = np.zeros_like(depth, dtype=np.float32)
+    values = depth[valid & np.isfinite(depth) & (depth > 0)]
+    if values.size == 0:
+        return np.zeros((*depth.shape, 3), dtype=np.uint8)
+    lo, hi = np.percentile(values, [2, 98])
+    if hi <= lo:
+        hi = lo + 1.0
+    vis = np.clip((depth - lo) / (hi - lo), 0, 1)
+    vis[~valid] = 0
+    colored = cv2.applyColorMap((vis * 255).astype(np.uint8), cv2.COLORMAP_TURBO)
+    colored[~valid] = 0
+    return cv2.cvtColor(colored, cv2.COLOR_BGR2RGB)
+
+
+def line_endpoints_on_mask(
+    y_center: float,
+    slope: float,
+    mask: np.ndarray,
+) -> tuple[tuple[int, int], tuple[int, int]] | None:
+    h, w = mask.shape
+    x_center = (w - 1) / 2.0
+    xs = np.arange(w, dtype=np.float32)
+    ys = np.rint(y_center + slope * (xs - x_center)).astype(np.int32)
+    in_frame = (ys >= 0) & (ys < h)
+    if not np.any(in_frame):
+        return None
+    valid_xs = xs[in_frame].astype(np.int32)
+    valid_ys = ys[in_frame]
+    on_mask = mask[valid_ys, valid_xs]
+    if np.any(on_mask):
+        valid_xs = valid_xs[on_mask]
+        valid_ys = valid_ys[on_mask]
+    left_index = int(np.argmin(valid_xs))
+    right_index = int(np.argmax(valid_xs))
+    return (
+        (int(valid_xs[left_index]), int(valid_ys[left_index])),
+        (int(valid_xs[right_index]), int(valid_ys[right_index])),
+    )
+
+
+def save_overlay(
+    path: Path,
+    rgb: np.ndarray,
+    obstacle_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    edges_y: list[int],
+    edge_slope: float = 0.0,
+) -> None:
+    overlay = rgb.copy()
+    overlay[amodal_mask] = (0.65 * overlay[amodal_mask] + 0.35 * np.array([0, 160, 255])).astype(np.uint8)
+    overlay[obstacle_mask] = (0.45 * overlay[obstacle_mask] + 0.55 * np.array([255, 60, 20])).astype(np.uint8)
+    for y in edges_y:
+        y = int(np.clip(y, 0, overlay.shape[0] - 1))
+        endpoints = line_endpoints_on_mask(float(y), edge_slope, amodal_mask)
+        if endpoints is None:
+            endpoints = ((0, y), (overlay.shape[1] - 1, y))
+        cv2.line(overlay, endpoints[0], endpoints[1], (80, 255, 80), 2)
+    Image.fromarray(overlay).save(path)
+
+
+def read_depth(path: str | Path, shape: tuple[int, int], depth_scale: float) -> np.ndarray:
+    path = Path(path)
+    if path.suffix.lower() == '.npy':
+        depth = np.load(path).astype(np.float32)
+    elif path.suffix.lower() == '.npz':
+        data = np.load(path)
+        depth = data[data.files[0]].astype(np.float32)
+    else:
+        raw = cv2.imread(str(path), cv2.IMREAD_UNCHANGED)
+        if raw is None:
+            raise FileNotFoundError(path)
+        if raw.ndim == 3:
+            raw = cv2.cvtColor(raw, cv2.COLOR_BGR2GRAY)
+        depth = raw.astype(np.float32)
+    h, w = shape
+    if depth.shape[:2] != (h, w):
+        if not _aspect_ratio_matches(depth.shape[:2], (h, w)):
+            raise ValueError(
+                f'Depth/RGB raster mismatch: depth={depth.shape[:2]}, rgb={(h, w)}. '
+                'Refusing to resize across incompatible aspect ratios because this usually indicates orientation or source mismatch.'
+            )
+        depth = cv2.resize(depth, (w, h), interpolation=cv2.INTER_LINEAR)
+    depth *= depth_scale
+    return depth
+
+
+def detect_stair_edge_model(
+    rgb: np.ndarray,
+    roi: np.ndarray,
+    max_edges: int,
+    min_gap_ratio: float = 0.025,
+    min_line_ratio: float = 0.10,
+    maximum_angle_degrees: float = 25.0,
+    hough_threshold_ratio: float = 0.02,
+    max_line_gap_ratio: float = 0.04,
+) -> tuple[list[int], float]:
+    h, w = roi.shape
+    x_center = (w - 1) / 2.0
+    gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+    gray = cv2.GaussianBlur(gray, (5, 5), 0)
+    median = float(np.median(gray[roi])) if np.any(roi) else float(np.median(gray))
+    lower = int(max(20, 0.66 * median))
+    upper = int(min(220, 1.33 * median + 20))
+    edges = cv2.Canny(gray, lower, upper)
+    edges[~roi] = 0
+    min_len = max(25, int(w * min_line_ratio))
+    lines = cv2.HoughLinesP(
+        edges,
+        rho=1,
+        theta=np.pi / 180,
+        threshold=max(20, int(w * hough_threshold_ratio)),
+        minLineLength=min_len,
+        maxLineGap=max(12, int(w * max_line_gap_ratio)),
+    )
+    if lines is None:
+        return [], 0.0
+
+    candidates: list[tuple[float, float, float]] = []
+    for line in lines[:, 0, :]:
+        x1, y1, x2, y2 = line.astype(float)
+        dx = x2 - x1
+        dy = y2 - y1
+        length = float(np.hypot(dx, dy))
+        if length < min_len:
+            continue
+        if abs(dx) < 1e-6:
+            continue
+        angle = abs(np.degrees(np.arctan2(dy, dx)))
+        angle = min(angle, abs(180 - angle))
+        if angle > maximum_angle_degrees:
+            continue
+        slope = dy / dx
+        y_at_center = y1 + slope * (x_center - x1)
+        if not (0.06 * h <= y_at_center <= 0.97 * h):
+            continue
+        candidates.append((y_at_center, slope, length))
+
+    if not candidates:
+        return [], 0.0
+
+    candidates.sort(key=lambda item: item[0])
+    min_gap = max(12, int(h * min_gap_ratio))
+    clusters: list[list[tuple[float, float, float]]] = []
+    for item in candidates:
+        if not clusters or item[0] - clusters[-1][-1][0] > min_gap:
+            clusters.append([item])
+        else:
+            clusters[-1].append(item)
+
+    merged: list[tuple[int, float, float]] = []
+    for cluster in clusters:
+        weights = np.array([item[2] for item in cluster], dtype=np.float32)
+        ys = np.array([item[0] for item in cluster], dtype=np.float32)
+        slopes = np.array([item[1] for item in cluster], dtype=np.float32)
+        merged.append((
+            int(round(float(np.average(ys, weights=weights)))),
+            float(np.average(slopes, weights=weights)),
+            float(weights.sum()),
+        ))
+
+    merged.sort(key=lambda item: item[2], reverse=True)
+    selected = sorted(merged[:max_edges], key=lambda item: item[0])
+    if not selected:
+        return [], 0.0
+    weights = np.array([item[2] for item in selected], dtype=np.float32)
+    slopes = np.array([item[1] for item in selected], dtype=np.float32)
+    maximum_slope = float(np.tan(np.radians(maximum_angle_degrees)))
+    dominant_slope = float(np.clip(np.average(slopes, weights=weights), -maximum_slope, maximum_slope))
+    return [int(item[0]) for item in selected], dominant_slope
+
+
+def detect_horizontal_edges(
+    rgb: np.ndarray,
+    roi: np.ndarray,
+    max_edges: int,
+    min_gap_ratio: float = 0.025,
+    min_line_ratio: float = 0.10,
+    maximum_angle_degrees: float = 25.0,
+    hough_threshold_ratio: float = 0.02,
+    max_line_gap_ratio: float = 0.04,
+) -> list[int]:
+    edges_y, _ = detect_stair_edge_model(
+        rgb,
+        roi,
+        max_edges,
+        min_gap_ratio=min_gap_ratio,
+        min_line_ratio=min_line_ratio,
+        maximum_angle_degrees=maximum_angle_degrees,
+        hough_threshold_ratio=hough_threshold_ratio,
+        max_line_gap_ratio=max_line_gap_ratio,
+    )
+    return edges_y
+
+
+def detect_horizontal_gradient_peaks(
+    rgb: np.ndarray,
+    roi: np.ndarray,
+    max_edges: int,
+    min_gap_ratio: float = 0.018,
+) -> list[int]:
+    """Recover stair tread rows when short perspective lines defeat Hough voting.
+
+    This detector is deliberately a secondary fallback: it aggregates vertical
+    image gradients only inside the reviewed visible stair mask and is used only
+    when the line detector found too few edges.
+    """
+    h, w = roi.shape
+    gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY)
+    gray = cv2.GaussianBlur(gray, (5, 5), 0)
+    vertical_gradient = np.abs(cv2.Sobel(gray, cv2.CV_32F, 0, 1, ksize=3))
+    scores = np.zeros(h, dtype=np.float32)
+    widths = roi.sum(axis=1)
+    minimum_row_pixels = max(8, int(w * 0.012))
+    for y in range(h):
+        values = vertical_gradient[y, roi[y]]
+        if values.size < minimum_row_pixels:
+            continue
+        strongest_count = max(1, int(values.size * 0.30))
+        scores[y] = float(np.partition(values, -strongest_count)[-strongest_count:].mean())
+    scores = cv2.GaussianBlur(scores[:, None], (1, 7), 0)[:, 0]
+    eligible = widths >= minimum_row_pixels
+    valid_scores = scores[eligible]
+    if valid_scores.size == 0 or float(valid_scores.max()) <= 0:
+        return []
+    threshold = max(
+        float(np.percentile(valid_scores, 60)),
+        float(np.median(valid_scores) + 0.25 * np.std(valid_scores)),
+    )
+    candidates = [
+        y
+        for y in range(2, h - 2)
+        if eligible[y]
+        and scores[y] >= threshold
+        and scores[y] >= float(scores[y - 2 : y + 3].max())
+    ]
+    minimum_gap = max(8, int(h * min_gap_ratio))
+    selected: list[int] = []
+    for y in sorted(candidates, key=lambda row: float(scores[row]), reverse=True):
+        if all(abs(y - other) > minimum_gap for other in selected):
+            selected.append(y)
+        if len(selected) >= max_edges:
+            break
+    return sorted(selected)
+
+
+def detect_depth_gradient_stair_edges(
+    depth: np.ndarray,
+    roi: np.ndarray,
+    max_edges: int,
+    min_gap_ratio: float = 0.020,
+) -> list[int]:
+    """Detect stair edges from depth map vertical gradient peaks.
+
+    This is a tertiary fallback for scenes where RGB Hough lines are
+    insufficient (e.g. distant/crowded stairs). Depth maps from
+    Depth Anything V2 often show clear discontinuities at step boundaries.
+    """
+    h, w = roi.shape
+    if not np.any(roi) or not np.any(np.isfinite(depth[roi])):
+        return []
+    depth_f = depth.astype(np.float32).copy()
+    depth_f[~np.isfinite(depth_f)] = 0.0
+    depth_smooth = cv2.GaussianBlur(depth_f, (7, 7), 0)
+    vertical_grad = np.abs(cv2.Sobel(depth_smooth, cv2.CV_32F, 0, 1, ksize=5))
+    scores = np.zeros(h, dtype=np.float32)
+    widths = roi.sum(axis=1)
+    min_row_px = max(6, int(w * 0.01))
+    for y in range(h):
+        vals = vertical_grad[y, roi[y]]
+        if vals.size < min_row_px:
+            continue
+        top_count = max(1, int(vals.size * 0.25))
+        scores[y] = float(np.partition(vals, -top_count)[-top_count:].mean())
+    scores = cv2.GaussianBlur(scores[:, None], (1, 9), 0)[:, 0]
+    eligible = widths >= min_row_px
+    valid_scores = scores[eligible]
+    if valid_scores.size == 0 or float(valid_scores.max()) <= 0:
+        return []
+    threshold = max(
+        float(np.percentile(valid_scores, 65)),
+        float(np.median(valid_scores) + 0.3 * np.std(valid_scores)),
+    )
+    candidates = [
+        y for y in range(2, h - 2)
+        if eligible[y]
+        and scores[y] >= threshold
+        and scores[y] >= float(scores[y - 2 : y + 3].max())
+    ]
+    min_gap = max(8, int(h * min_gap_ratio))
+    selected: list[int] = []
+    for y in sorted(candidates, key=lambda row: float(scores[row]), reverse=True):
+        if all(abs(y - other) > min_gap for other in selected):
+            selected.append(y)
+        if len(selected) >= max_edges:
+            break
+    return sorted(selected)
+
+
+def stair_edge_coverage_ratio(edges_y: list[int], mask: np.ndarray) -> float:
+    rows = np.where(mask)[0]
+    if len(edges_y) < 2 or rows.size == 0:
+        return 0.0
+    target_span = max(int(rows.max() - rows.min()), 1)
+    return float((max(edges_y) - min(edges_y)) / target_span)
+
+
+def fallback_edges(mask: np.ndarray, count: int) -> list[int]:
+    ys = np.where(mask)[0]
+    h = mask.shape[0]
+    if ys.size == 0:
+        top, bottom = int(0.15 * h), int(0.92 * h)
+    else:
+        top, bottom = int(np.percentile(ys, 8)), int(np.percentile(ys, 96))
+    if bottom <= top:
+        return []
+    return [int(round(v)) for v in np.linspace(top, bottom, count + 2)[1:-1]]
+
+
+def merge_edge_positions(edges: Iterable[int], min_gap: int) -> list[int]:
+    values = sorted(int(v) for v in edges)
+    if not values:
+        return []
+    clusters: list[list[int]] = []
+    for value in values:
+        if not clusters or value - clusters[-1][-1] > min_gap:
+            clusters.append([value])
+        else:
+            clusters[-1].append(value)
+    return [int(round(float(np.mean(cluster)))) for cluster in clusters]
+
+
+def make_step_prior_depth(shape: tuple[int, int], edges_y: list[int], near: float, far: float) -> np.ndarray:
+    h, w = shape
+    yy = np.linspace(0, 1, h, dtype=np.float32)[:, None]
+    base = near + (1.0 - yy) * (far - near)
+    depth = np.repeat(base, w, axis=1)
+
+    boundaries = [0] + sorted(int(y) for y in edges_y if 0 < y < h - 1) + [h]
+    if len(boundaries) > 2:
+        n_bands = len(boundaries) - 1
+        for band_idx, (top, bottom) in enumerate(zip(boundaries[:-1], boundaries[1:])):
+            band_height = max(1, bottom - top)
+            local = np.linspace(0, 1, band_height, dtype=np.float32)[:, None]
+            # Top bands are farther away; lower bands are closer. Keeping a
+            # slight within-band slope avoids fully flat cardboard strips.
+            band_far = far - (far - near) * band_idx / n_bands
+            band_near = far - (far - near) * (band_idx + 0.72) / n_bands
+            depth[top:bottom, :] = band_far + local * (band_near - band_far)
+    return depth.astype(np.float32)
+
+
+def make_continuous_prior_depth(shape: tuple[int, int], near: float, far: float) -> np.ndarray:
+    h, w = shape
+    yy = np.linspace(0.0, 1.0, h, dtype=np.float32)[:, None]
+    depth = far - yy * (far - near)
+    return np.repeat(depth, w, axis=1).astype(np.float32)
+
+
+def camera_intrinsics(w: int, h: int, fx: float | None, fy: float | None, cx: float | None, cy: float | None):
+    default_f = float(max(w, h))
+    fx = default_f if fx is None else fx
+    fy = default_f if fy is None else fy
+    cx = (w - 1) / 2.0 if cx is None else cx
+    cy = (h - 1) / 2.0 if cy is None else cy
+    return fx, fy, cx, cy
+
+
+def pixels_to_points(depth: np.ndarray, fx: float, fy: float, cx: float, cy: float):
+    h, w = depth.shape
+    xs, ys = np.meshgrid(np.arange(w, dtype=np.float32), np.arange(h, dtype=np.float32))
+    z = depth.astype(np.float32)
+    x = (xs - cx) * z / fx
+    y = (ys - cy) * z / fy
+    return np.stack([x, y, z], axis=-1)
+
+
+def fit_plane(points: np.ndarray):
+    if points.shape[0] < 50:
+        return None
+    centroid = points.mean(axis=0)
+    centered = points - centroid
+    try:
+        _, _, vh = np.linalg.svd(centered, full_matrices=False)
+    except np.linalg.LinAlgError:
+        return None
+    normal = vh[-1]
+    norm = np.linalg.norm(normal)
+    if norm < 1e-6:
+        return None
+    normal = normal / norm
+    d = -float(np.dot(normal, centroid))
+    return normal.astype(np.float32), d
+
+
+def intersect_plane_for_pixels(shape: tuple[int, int], plane, fx: float, fy: float, cx: float, cy: float) -> np.ndarray:
+    h, w = shape
+    normal, d = plane
+    xs, ys = np.meshgrid(np.arange(w, dtype=np.float32), np.arange(h, dtype=np.float32))
+    rays = np.stack([(xs - cx) / fx, (ys - cy) / fy, np.ones((h, w), dtype=np.float32)], axis=-1)
+    denom = rays @ normal
+    with np.errstate(divide='ignore', invalid='ignore'):
+        t = -d / denom
+    t[~np.isfinite(t)] = 0
+    t[t <= 0] = 0
+    return t.astype(np.float32)
+
+
+def inpaint_depth(depth: np.ndarray, fill_mask: np.ndarray, valid: np.ndarray) -> np.ndarray:
+    values = depth[valid & np.isfinite(depth) & (depth > 0)]
+    if values.size == 0:
+        return depth.copy()
+    lo, hi = np.percentile(values, [1, 99])
+    if hi <= lo:
+        hi = lo + 1.0
+    normalized = np.clip((depth - lo) / (hi - lo), 0, 1)
+    normalized[~np.isfinite(normalized)] = float(np.median(normalized[valid]))
+    filled = cv2.inpaint((normalized * 255).astype(np.uint8), fill_mask.astype(np.uint8) * 255, 5, cv2.INPAINT_TELEA)
+    return filled.astype(np.float32) / 255.0 * (hi - lo) + lo
+
+
+def inpaint_rgb(rgb: np.ndarray, fill_mask: np.ndarray, radius: float = 5.0) -> np.ndarray:
+    if not np.any(fill_mask):
+        return rgb.copy()
+    bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+    inpainted = cv2.inpaint(bgr, fill_mask.astype(np.uint8) * 255, radius, cv2.INPAINT_TELEA)
+    return cv2.cvtColor(inpainted, cv2.COLOR_BGR2RGB)
+
+
+def stair_band_mask(
+    shape: tuple[int, int],
+    top: float,
+    bottom: float,
+    stair_edge_slope: float = 0.0,
+) -> np.ndarray:
+    """Return one tread/riser band aligned with the observed image perspective.
+
+    ``edges_y`` are measured at the image centre.  A non-zero slope means that
+    the same edge moves vertically across the frame, so horizontal image rows
+    would mix different physical steps.  This helper preserves the legacy
+    horizontal behaviour when the slope is zero.
+    """
+    h, w = shape
+    ys, xs = np.indices((h, w), dtype=np.float32)
+    center_x = (w - 1) * 0.5
+    centerline_y = ys - float(stair_edge_slope) * (xs - center_x)
+    return (centerline_y >= float(top)) & (centerline_y < float(bottom))
+
+
+def complete_depth_by_planes(
+    depth: np.ndarray,
+    obstacle_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    edges_y: list[int],
+    fx: float,
+    fy: float,
+    cx: float,
+    cy: float,
+    min_fit_points: int,
+    stair_edge_slope: float = 0.0,
+):
+    h, w = depth.shape
+    completed = depth.copy()
+    visible = amodal_mask & ~obstacle_mask & np.isfinite(depth) & (depth > 0)
+    inpainted = inpaint_depth(depth, obstacle_mask & amodal_mask, visible)
+    points = pixels_to_points(depth, fx, fy, cx, cy)
+    confidence = np.zeros(depth.shape, dtype=np.float32)
+    distance_to_visible = cv2.distanceTransform((~visible).astype(np.uint8), cv2.DIST_L2, 5)
+    plane_blend_scale = max(8.0, 0.025 * float(np.hypot(*depth.shape)))
+    plane_weight = np.clip(distance_to_visible / plane_blend_scale, 0.0, 0.85)
+
+    boundaries = [0] + sorted(int(y) for y in edges_y if 0 < y < h - 1) + [h]
+    fitted_planes = []
+    for top, bottom in zip(boundaries[:-1], boundaries[1:]):
+        band = stair_band_mask((h, w), top, bottom, stair_edge_slope)
+        fit_mask = band & visible
+        fill_mask = band & obstacle_mask & amodal_mask
+        plane = None
+        if int(fit_mask.sum()) >= min_fit_points:
+            sample = points[fit_mask]
+            if sample.shape[0] > 30000:
+                sample = sample[np.linspace(0, sample.shape[0] - 1, 30000).astype(np.int64)]
+            plane = fit_plane(sample)
+        if plane is not None:
+            plane_depth = intersect_plane_for_pixels((h, w), plane, fx, fy, cx, cy)
+            ok = fill_mask & (plane_depth > 0) & np.isfinite(plane_depth)
+            completed[ok] = (
+                plane_weight[ok] * plane_depth[ok]
+                + (1.0 - plane_weight[ok]) * inpainted[ok]
+            )
+            missing = fill_mask & ~ok
+            completed[missing] = inpainted[missing]
+            residual = np.abs(sample @ plane[0] + plane[1])
+            scale = max(float(np.median(sample[:, 2])), 1e-6)
+            quality = float(np.exp(-12.0 * np.median(residual) / scale))
+            confidence[ok] = np.clip(quality, 0.35, 0.95)
+            confidence[missing] = 0.25
+            mode = 'plane_diagonal' if abs(stair_edge_slope) > 1e-6 else 'plane'
+            fitted_planes.append((top, bottom, int(fit_mask.sum()), mode))
+        else:
+            completed[fill_mask] = inpainted[fill_mask]
+            confidence[fill_mask] = 0.20
+            mode = 'inpaint_fallback_diagonal' if abs(stair_edge_slope) > 1e-6 else 'inpaint_fallback'
+            fitted_planes.append((top, bottom, int(fit_mask.sum()), mode))
+
+    return completed, fitted_planes, confidence
+
+
+def robust_fit_plane(points: np.ndarray, min_points: int):
+    if points.shape[0] < min_points:
+        return None, 0.0, 0
+    sample = points
+    if sample.shape[0] > 50000:
+        sample = sample[np.linspace(0, sample.shape[0] - 1, 50000).astype(np.int64)]
+    plane = None
+    for _ in range(4):
+        plane = fit_plane(sample)
+        if plane is None:
+            return None, 0.0, int(sample.shape[0])
+        residual = np.abs(sample @ plane[0] + plane[1])
+        median = float(np.median(residual))
+        mad = float(np.median(np.abs(residual - median)))
+        threshold = max(median + 2.5 * max(mad, 1e-6), float(np.percentile(residual, 70)))
+        retained = sample[residual <= threshold]
+        if retained.shape[0] < min_points or retained.shape[0] >= sample.shape[0] * 0.98:
+            break
+        sample = retained
+    if plane is None:
+        return None, 0.0, int(sample.shape[0])
+    residual = np.abs(sample @ plane[0] + plane[1])
+    scale = max(float(np.median(sample[:, 2])), 1e-6)
+    quality = float(np.exp(-10.0 * float(np.median(residual)) / scale))
+    return plane, float(np.clip(quality, 0.0, 1.0)), int(sample.shape[0])
+
+
+def complete_depth_continuous_surface(
+    depth: np.ndarray,
+    completion_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    fx: float,
+    fy: float,
+    cx: float,
+    cy: float,
+    min_fit_points: int,
+):
+    completed = depth.copy()
+    confidence = np.zeros(depth.shape, dtype=np.float32)
+    visible = amodal_mask & ~completion_mask & np.isfinite(depth) & (depth > 0)
+    inpainted = inpaint_depth(depth, completion_mask, visible)
+    points = pixels_to_points(depth, fx, fy, cx, cy)
+    plane, quality, sample_count = robust_fit_plane(points[visible], min_fit_points)
+    method = 'edge_aware_inpaint'
+    if plane is None:
+        completed[completion_mask] = inpainted[completion_mask]
+        distance_to_visible = cv2.distanceTransform((~visible).astype(np.uint8), cv2.DIST_L2, 5)
+        distance_scale = max(8.0, 0.06 * float(np.hypot(*depth.shape)))
+        distance_confidence = np.exp(-distance_to_visible / distance_scale)
+        confidence[completion_mask] = np.clip(
+            0.20 + 0.25 * distance_confidence[completion_mask],
+            0.20,
+            0.45,
+        )
+        return completed, [(0, depth.shape[0], sample_count, method)], confidence
+
+    plane_depth = intersect_plane_for_pixels(depth.shape, plane, fx, fy, cx, cy)
+    visible_values = depth[visible]
+    low, high = np.percentile(visible_values, [1, 99])
+    plausible = (
+        completion_mask
+        & np.isfinite(plane_depth)
+        & (plane_depth > max(1e-6, 0.50 * low))
+        & (plane_depth < 1.50 * high)
+    )
+    # Keep local boundary detail from inpainting while the robust plane supplies
+    # a stable global surface through larger occluders.
+    distance_to_visible = cv2.distanceTransform((~visible).astype(np.uint8), cv2.DIST_L2, 5)
+    plane_blend_scale = max(8.0, 0.025 * float(np.hypot(*depth.shape)))
+    plane_weight = np.clip(distance_to_visible / plane_blend_scale, 0.0, 0.85)
+    completed[plausible] = (
+        plane_weight[plausible] * plane_depth[plausible]
+        + (1.0 - plane_weight[plausible]) * inpainted[plausible]
+    )
+    fallback = completion_mask & ~plausible
+    completed[fallback] = inpainted[fallback]
+
+    distance_scale = max(8.0, 0.06 * float(np.hypot(*depth.shape)))
+    distance_confidence = np.exp(-distance_to_visible / distance_scale)
+    confidence[plausible] = np.clip(quality * distance_confidence[plausible], 0.25, 0.95)
+    confidence[fallback] = np.clip(
+        0.20 + 0.35 * distance_confidence[fallback],
+        0.20,
+        0.55,
+    )
+    method = 'robust_continuous_plane_plus_edge_aware_inpaint'
+    return completed, [(0, depth.shape[0], sample_count, method)], confidence
+
+
+def complete_depth_generic_inpaint(
+    depth: np.ndarray, completion_mask: np.ndarray, amodal_mask: np.ndarray
+):
+    visible = amodal_mask & ~completion_mask & np.isfinite(depth) & (depth > 0)
+    completed = depth.copy()
+    inpainted = inpaint_depth(depth, completion_mask, visible)
+    completed[completion_mask] = inpainted[completion_mask]
+    confidence = np.zeros(depth.shape, dtype=np.float32)
+    confidence[completion_mask] = 0.20
+    return completed, [(0, depth.shape[0], int(visible.sum()), 'edge_aware_inpaint')], confidence
+
+
+def enforce_hidden_boundary_continuity(
+    completed: np.ndarray,
+    source_depth: np.ndarray,
+    visible: np.ndarray,
+    hidden: np.ndarray,
+    radius: int,
+    anchor_power: float = 0.45,
+) -> np.ndarray:
+    if radius <= 0 or not np.any(hidden) or not np.any(visible):
+        return completed
+    size = radius * 2 + 1
+    sums = cv2.boxFilter(
+        np.where(visible, source_depth, 0.0).astype(np.float32),
+        -1,
+        (size, size),
+        normalize=False,
+        borderType=cv2.BORDER_CONSTANT,
+    )
+    counts = cv2.boxFilter(
+        visible.astype(np.float32),
+        -1,
+        (size, size),
+        normalize=False,
+        borderType=cv2.BORDER_CONSTANT,
+    )
+    boundary = hidden & (counts > 0)
+    if not np.any(boundary):
+        return completed
+    neighbor_depth = np.zeros_like(completed, dtype=np.float32)
+    neighbor_depth[boundary] = sums[boundary] / counts[boundary]
+    distance = cv2.distanceTransform((~visible).astype(np.uint8), cv2.DIST_L2, 5)
+    raw_anchor = 1.0 - np.clip((distance - 1.0) / max(float(radius), 1.0), 0.0, 1.0)
+    anchor_weight = np.power(raw_anchor, max(float(anchor_power), 1e-3))
+    output = completed.copy()
+    output[boundary] = (
+        (1.0 - anchor_weight[boundary]) * completed[boundary]
+        + anchor_weight[boundary] * neighbor_depth[boundary]
+    )
+    return output
+
+
+DEPTH_PLAUSIBILITY_POLICIES = {
+    # Stairs legitimately span several depth layers, so retain a wider target
+    # envelope.  A plane/ray intersection must still stay inside the robust
+    # numerical domain observed in the source depth map.
+    'stairs': {
+        'target_span_margin': 1.00,
+        'maximum_correction_ratio': 0.05,
+    },
+    # A reviewed walkable surface or ramp should be locally continuous.  The
+    # margin remains wide enough for perspective extrapolation already accepted
+    # by complete_depth_continuous_surface.
+    'walkable': {
+        'target_span_margin': 0.75,
+        'maximum_correction_ratio': 0.02,
+    },
+    'ramp': {
+        'target_span_margin': 0.75,
+        'maximum_correction_ratio': 0.02,
+    },
+    # Generic mode has the weakest category prior, but it may not invent an
+    # unbounded scale outside the observed depth domain.
+    'generic': {
+        'target_span_margin': 1.50,
+        'maximum_correction_ratio': 0.05,
+    },
+}
+
+
+def enforce_hidden_depth_plausibility(
+    completed: np.ndarray,
+    source_depth: np.ndarray,
+    visible: np.ndarray,
+    hidden: np.ndarray,
+    geometry_mode: str,
+) -> tuple[np.ndarray, np.ndarray, dict]:
+    """Reject numerically implausible hidden depths and return an audit record.
+
+    Plane/ray intersections can explode when a fitted plane is nearly parallel
+    to a camera ray.  This guard is deliberately conservative:
+
+    * only hidden pixels may be changed;
+    * the accepted range is inferred from the observed source-depth scale, not
+      assumed to be metric;
+    * category-specific target margins allow layered stairs more variation than
+      continuous walkable surfaces and ramps;
+    * rejected values use bounded edge-aware inpainting instead of clipping a
+      singular plane to a hard wall.
+
+    The returned correction mask is suitable for lowering confidence and for a
+    review overlay.  A large correction ratio is marked as withheld in the
+    audit rather than silently presented as a trustworthy geometry candidate.
+    """
+    if completed.shape != source_depth.shape:
+        raise ValueError(
+            f'Completed/source depth shape mismatch: {completed.shape} != {source_depth.shape}'
+        )
+    if visible.shape != completed.shape or hidden.shape != completed.shape:
+        raise ValueError('Visible/hidden masks must share the completed-depth raster')
+    if geometry_mode not in DEPTH_PLAUSIBILITY_POLICIES:
+        raise ValueError(f'Unsupported geometry mode for depth plausibility: {geometry_mode!r}')
+
+    hidden = hidden.astype(bool)
+    visible = visible.astype(bool) & ~hidden
+    policy = DEPTH_PLAUSIBILITY_POLICIES[geometry_mode]
+    hidden_count = int(hidden.sum())
+    empty_corrections = np.zeros(completed.shape, dtype=bool)
+    if hidden_count == 0:
+        return completed.copy(), empty_corrections, {
+            'policy': f'{geometry_mode}_observed_depth_domain_v1',
+            'status': 'not_applicable_empty_hidden_region',
+            'candidate_eligible_for_review': True,
+            'hidden_pixel_count': 0,
+            'corrected_pixel_count': 0,
+            'corrected_ratio': 0.0,
+            'maximum_correction_ratio': float(policy['maximum_correction_ratio']),
+            'source_depth_is_treated_as_metric_truth': False,
+        }
+
+    source_valid = np.isfinite(source_depth) & (source_depth > 0)
+    source_values = source_depth[source_valid]
+    visible_valid = visible & source_valid
+    visible_values = source_depth[visible_valid]
+    if source_values.size == 0 or visible_values.size == 0:
+        invalid = hidden & (
+            ~np.isfinite(completed)
+            | (completed <= 0)
+        )
+        return completed.copy(), invalid, {
+            'policy': f'{geometry_mode}_observed_depth_domain_v1',
+            'status': 'withheld_no_visible_depth_support',
+            'candidate_eligible_for_review': False,
+            'hidden_pixel_count': hidden_count,
+            'corrected_pixel_count': 0,
+            'corrected_ratio': 0.0,
+            'maximum_correction_ratio': float(policy['maximum_correction_ratio']),
+            'source_depth_is_treated_as_metric_truth': False,
+            'reason': 'No positive finite visible target depth was available for a bounded fallback.',
+        }
+
+    source_q001, source_q999 = np.percentile(source_values, [0.1, 99.9])
+    source_span = max(
+        float(source_q999 - source_q001),
+        0.05 * abs(float(np.median(source_values))),
+        1e-6,
+    )
+    # Ignore isolated source-map outliers while never extending beyond the
+    # finite positive range actually emitted by the depth estimator.
+    source_lower = max(
+        float(source_values.min()),
+        float(source_q001 - 0.10 * source_span),
+    )
+    source_upper = min(
+        float(source_values.max()),
+        float(source_q999 + 0.10 * source_span),
+    )
+
+    target_q01, target_q99 = np.percentile(visible_values, [1.0, 99.0])
+    target_span = max(
+        float(target_q99 - target_q01),
+        0.05 * abs(float(np.median(visible_values))),
+        1e-6,
+    )
+    target_margin = float(policy['target_span_margin']) * target_span
+    accepted_lower = max(source_lower, float(target_q01 - target_margin))
+    accepted_upper = min(source_upper, float(target_q99 + target_margin))
+    if not np.isfinite(accepted_lower) or not np.isfinite(accepted_upper) or accepted_upper < accepted_lower:
+        accepted_lower, accepted_upper = source_lower, source_upper
+
+    corrections = hidden & (
+        ~np.isfinite(completed)
+        | (completed < accepted_lower)
+        | (completed > accepted_upper)
+    )
+    corrected_count = int(corrections.sum())
+    output = completed.copy()
+    if corrected_count:
+        fallback = inpaint_depth(source_depth, hidden, visible_valid)
+        fallback = np.nan_to_num(
+            fallback,
+            nan=float(np.median(visible_values)),
+            posinf=accepted_upper,
+            neginf=accepted_lower,
+        )
+        fallback = np.clip(fallback, accepted_lower, accepted_upper)
+        output[corrections] = fallback[corrections]
+
+    # Preserve source depth bit-for-bit outside the reviewed hidden region.
+    output[~hidden] = source_depth[~hidden]
+    corrected_ratio = float(corrected_count / hidden_count)
+    maximum_correction_ratio = float(policy['maximum_correction_ratio'])
+    candidate_eligible = bool(
+        corrected_ratio <= maximum_correction_ratio
+        and np.all(np.isfinite(output[hidden]))
+        and np.all(output[hidden] >= accepted_lower)
+        and np.all(output[hidden] <= accepted_upper)
+    )
+    if not candidate_eligible:
+        status = 'withheld_excessive_depth_corrections'
+    elif corrected_count:
+        status = 'corrected_sparse_depth_outliers'
+    else:
+        status = 'within_observed_depth_domain'
+    audit = {
+        'policy': f'{geometry_mode}_observed_depth_domain_v1',
+        'status': status,
+        'candidate_eligible_for_review': candidate_eligible,
+        'hidden_pixel_count': hidden_count,
+        'corrected_pixel_count': corrected_count,
+        'corrected_ratio': corrected_ratio,
+        'maximum_correction_ratio': maximum_correction_ratio,
+        'accepted_depth_lower': float(accepted_lower),
+        'accepted_depth_upper': float(accepted_upper),
+        'observed_source_depth_min': float(source_values.min()),
+        'observed_source_depth_max': float(source_values.max()),
+        'visible_target_depth_p01': float(target_q01),
+        'visible_target_depth_p99': float(target_q99),
+        'source_depth_is_treated_as_metric_truth': False,
+    }
+    return output, corrections, audit
+
+
+def write_point_cloud_ply(path: Path, points: np.ndarray, colors: np.ndarray, mask: np.ndarray, stride: int) -> int:
+    sampled = np.zeros(mask.shape, dtype=bool)
+    sampled[::stride, ::stride] = True
+    use = mask & sampled & np.all(np.isfinite(points), axis=-1) & (points[..., 2] > 0)
+    pts = points[use]
+    cols = colors[use]
+    with open(path, 'w', encoding='ascii') as f:
+        f.write('ply\nformat ascii 1.0\n')
+        f.write(f'element vertex {len(pts)}\n')
+        f.write('property float x\nproperty float y\nproperty float z\n')
+        f.write('property uchar red\nproperty uchar green\nproperty uchar blue\n')
+        f.write('end_header\n')
+        for p, c in zip(pts, cols):
+            f.write(f'{p[0]:.6f} {p[1]:.6f} {p[2]:.6f} {int(c[0])} {int(c[1])} {int(c[2])}\n')
+    return int(len(pts))
+
+
+def write_mesh_ply(path: Path, points: np.ndarray, colors: np.ndarray, mask: np.ndarray, stride: int, max_depth_jump: float) -> tuple[int, int]:
+    h, w = mask.shape
+    ys = np.arange(0, h, stride)
+    xs = np.arange(0, w, stride)
+    vertex_id = -np.ones((len(ys), len(xs)), dtype=np.int64)
+    vertices = []
+    vertex_colors = []
+    for iy, y in enumerate(ys):
+        for ix, x in enumerate(xs):
+            if mask[y, x] and np.isfinite(points[y, x]).all() and points[y, x, 2] > 0:
+                vertex_id[iy, ix] = len(vertices)
+                vertices.append(points[y, x])
+                vertex_colors.append(colors[y, x])
+
+    faces = []
+    for iy in range(len(ys) - 1):
+        for ix in range(len(xs) - 1):
+            ids = [vertex_id[iy, ix], vertex_id[iy, ix + 1], vertex_id[iy + 1, ix], vertex_id[iy + 1, ix + 1]]
+            if min(ids) < 0:
+                continue
+            z = np.array([vertices[i][2] for i in ids], dtype=np.float32)
+            if float(z.max() - z.min()) > max_depth_jump:
+                continue
+            faces.append((ids[0], ids[2], ids[1]))
+            faces.append((ids[1], ids[2], ids[3]))
+
+    with open(path, 'w', encoding='ascii') as f:
+        f.write('ply\nformat ascii 1.0\n')
+        f.write(f'element vertex {len(vertices)}\n')
+        f.write('property float x\nproperty float y\nproperty float z\n')
+        f.write('property uchar red\nproperty uchar green\nproperty uchar blue\n')
+        f.write(f'element face {len(faces)}\n')
+        f.write('property list uchar int vertex_indices\n')
+        f.write('end_header\n')
+        for p, c in zip(vertices, vertex_colors):
+            f.write(f'{p[0]:.6f} {p[1]:.6f} {p[2]:.6f} {int(c[0])} {int(c[1])} {int(c[2])}\n')
+        for face in faces:
+            f.write(f'3 {face[0]} {face[1]} {face[2]}\n')
+    return int(len(vertices)), int(len(faces))
+
+
+CATEGORY_GEOMETRY_MODES = {
+    'stairs': 'stairs',
+    'ramp': 'ramp',
+    'walkway': 'walkable',
+    'walkable': 'walkable',
+    'curb_cut': 'walkable',
+    'raised_curb': 'walkable',
+    'tactile_paving': 'walkable',
+    'unknown': 'generic',
+}
+
+
+def resolve_geometry_mode(category, requested_mode):
+    """Infer a safe mode from category and reject contradictory geometry priors."""
+    if category is None:
+        return requested_mode or 'stairs'
+    expected_mode = CATEGORY_GEOMETRY_MODES[category]
+    if requested_mode is not None and requested_mode != expected_mode:
+        raise ValueError(
+            f'Category {category!r} requires geometry mode {expected_mode!r}; '
+            f'got {requested_mode!r}'
+        )
+    return expected_mode
+
+
+def run(args):
+    if not args.image:
+        raise ValueError("--image is required")
+    args.geometry_mode = resolve_geometry_mode(
+        getattr(args, 'category', None),
+        getattr(args, 'geometry_mode', None),
+    )
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    source_shape = display_shape(args.image)
+    rgb = read_rgb(args.image, args.max_size)
+    h, w = rgb.shape[:2]
+    shape = (h, w)
+
+    if args.amodal_mask:
+        amodal_mask = read_source_grid_mask(args.amodal_mask, source_shape, shape)
+        amodal_source = args.amodal_mask
+    else:
+        amodal_mask = default_amodal_mask(shape)
+        amodal_source = 'default lower-scene mask'
+
+    if args.obstacle_mask:
+        obstacle_mask = read_source_grid_mask(args.obstacle_mask, source_shape, shape)
+        obstacle_source = args.obstacle_mask
+    else:
+        boxes = args.occlusion_box
+        if not boxes and not args.no_default_obstacle:
+            boxes = [DEFAULT_OBSTACLE_BOX]
+        obstacle_mask = boxes_to_mask(boxes, shape) if boxes else np.zeros(shape, dtype=bool)
+        obstacle_source = 'occlusion boxes' if boxes else 'empty obstacle mask'
+
+    obstacle_mask &= amodal_mask
+    if args.visible_mask:
+        visible_mask = read_source_grid_mask(args.visible_mask, source_shape, shape) & amodal_mask & ~obstacle_mask
+        visible_source = args.visible_mask
+        completion_mask = amodal_mask & ~visible_mask
+    else:
+        visible_mask = amodal_mask & ~obstacle_mask
+        visible_source = 'amodal mask minus obstacle mask'
+        completion_mask = obstacle_mask & amodal_mask
+
+    geometry_mode = args.geometry_mode
+    reference_edges: list[int] = []
+    target_edges: list[int] = []
+    edges_y: list[int] = []
+    reference_edge_slope = 0.0
+    target_edge_slope = 0.0
+    stair_edge_slope = 0.0
+    edge_source = 'not_applicable_for_continuous_surface'
+    used_regular_fallback_edges = False
+    used_perspective_edge_expansion = False
+    used_gradient_edge_expansion = False
+    used_depth_gradient_edge_expansion = False
+    stair_edge_confidence = 1.0 if geometry_mode != 'stairs' else 0.0
+    stair_edge_coverage = 1.0 if geometry_mode != 'stairs' else 0.0
+    if geometry_mode == 'stairs':
+        reference_rgb = None
+        if args.stair_edge_y:
+            edges_y = sorted(set(int(y) for y in args.stair_edge_y if 0 < int(y) < h - 1))
+            stair_edge_slope = float(np.tan(np.radians(args.stair_edge_angle_degrees)))
+            edge_source = 'reviewed stair edge y positions'
+            stair_edge_confidence = 1.0
+            stair_edge_coverage = stair_edge_coverage_ratio(edges_y, amodal_mask)
+        elif args.reference_image and Path(args.reference_image).exists():
+            reference_rgb = read_rgb(args.reference_image, max_size=max(h, w))
+            if reference_rgb.shape[:2] != shape:
+                if not _aspect_ratio_matches(reference_rgb.shape[:2], shape):
+                    raise ValueError(
+                        f'Reference RGB/target raster mismatch: reference={reference_rgb.shape[:2]}, target={shape}. '
+                        'Refusing to resize across incompatible aspect ratios because the reference supplies stair-edge evidence.'
+                    )
+                reference_rgb = cv2.resize(reference_rgb, (w, h), interpolation=cv2.INTER_AREA)
+            reference_edges, reference_edge_slope = detect_stair_edge_model(
+                reference_rgb,
+                amodal_mask,
+                args.max_step_edges,
+            )
+
+        if not args.stair_edge_y:
+            target_edges, target_edge_slope = detect_stair_edge_model(rgb, visible_mask, args.max_step_edges)
+            if reference_edges and len(reference_edges) >= len(target_edges):
+                edges_y = reference_edges
+                stair_edge_slope = reference_edge_slope
+                edge_source = args.reference_image
+            elif target_edges:
+                edges_y = target_edges
+                stair_edge_slope = target_edge_slope
+                edge_source = args.image
+            else:
+                edge_source = 'regular fallback edges'
+
+            initial_coverage = stair_edge_coverage_ratio(edges_y, amodal_mask)
+            if initial_coverage < args.minimum_auto_stair_edge_coverage:
+                relaxed_target, relaxed_target_slope = detect_stair_edge_model(
+                    rgb,
+                    visible_mask,
+                    args.max_step_edges,
+                    min_gap_ratio=0.025,
+                    min_line_ratio=0.08,
+                    maximum_angle_degrees=30.0,
+                    hough_threshold_ratio=0.015,
+                    max_line_gap_ratio=0.05,
+                )
+                relaxed_reference = []
+                relaxed_reference_slope = 0.0
+                if reference_rgb is not None:
+                    relaxed_reference, relaxed_reference_slope = detect_stair_edge_model(
+                        reference_rgb,
+                        amodal_mask,
+                        args.max_step_edges,
+                        min_gap_ratio=0.025,
+                        min_line_ratio=0.08,
+                        maximum_angle_degrees=30.0,
+                        hough_threshold_ratio=0.015,
+                        max_line_gap_ratio=0.05,
+                    )
+                expanded = merge_edge_positions(
+                    edges_y + relaxed_target + relaxed_reference,
+                    max(8, int(h * 0.018)),
+                )
+                expanded_coverage = stair_edge_coverage_ratio(expanded, amodal_mask)
+                if expanded_coverage > initial_coverage:
+                    edges_y = expanded[: args.max_step_edges]
+                    if abs(stair_edge_slope) < 1e-6:
+                        stair_edge_slope = relaxed_target_slope or relaxed_reference_slope
+                    edge_source = f'{edge_source} + perspective-tolerant expansion'
+                    used_perspective_edge_expansion = True
+
+            if len(edges_y) < args.minimum_detected_step_edges:
+                gradient_edges = detect_horizontal_gradient_peaks(
+                    rgb,
+                    visible_mask,
+                    args.max_step_edges,
+                )
+                expanded = merge_edge_positions(
+                    edges_y + gradient_edges,
+                    max(8, int(h * 0.018)),
+                )
+                if len(expanded) > len(edges_y):
+                    edges_y = expanded[: args.max_step_edges]
+                    edge_source = f'{edge_source} + visible-mask row-gradient expansion'
+                    used_gradient_edge_expansion = True
+
+            fallback = fallback_edges(amodal_mask, args.fallback_step_edges)
+            if len(edges_y) < args.minimum_detected_step_edges:
+                edges_y = merge_edge_positions(edges_y + fallback, max(10, int(h * 0.035)))
+                edge_source = (
+                    f'{edge_source} + regular fallback edges'
+                    if edge_source != 'regular fallback edges'
+                    else edge_source
+                )
+                used_regular_fallback_edges = True
+                stair_edge_confidence = 0.25
+            else:
+                stair_edge_coverage = stair_edge_coverage_ratio(edges_y, amodal_mask)
+                count_score = min(len(edges_y) / 5.0, 1.0)
+                coverage_score = min(
+                    stair_edge_coverage / max(args.minimum_auto_stair_edge_coverage, 1e-6),
+                    1.0,
+                )
+                stair_edge_confidence = float(
+                    np.clip(0.30 + 0.25 * count_score + 0.35 * coverage_score, 0.0, 0.90)
+                )
+                if used_gradient_edge_expansion:
+                    stair_edge_confidence = min(stair_edge_confidence, 0.75)
+            if not edges_y:
+                edges_y = fallback
+                used_regular_fallback_edges = bool(edges_y)
+            stair_edge_coverage = stair_edge_coverage_ratio(edges_y, amodal_mask)
+            if len(edges_y) < args.minimum_detected_step_edges:
+                stair_edge_slope = 0.0
+
+    if args.depth:
+        depth = read_depth(args.depth, shape, args.depth_scale)
+        depth_source = args.depth
+    else:
+        if geometry_mode == 'stairs':
+            depth = make_step_prior_depth(shape, edges_y, args.synthetic_near, args.synthetic_far)
+            depth_source = 'synthetic perspective stair prior'
+        else:
+            depth = make_continuous_prior_depth(shape, args.synthetic_near, args.synthetic_far)
+            depth_source = 'synthetic continuous perspective prior'
+
+    # --- Post-depth stair edge expansion using depth gradient ---
+    # When a real depth map is available and RGB-based coverage is still low,
+    # try to find additional stair edges from depth vertical gradient peaks.
+    if (
+        geometry_mode == 'stairs'
+        and args.depth
+        and not args.stair_edge_y
+        and stair_edge_coverage < args.minimum_auto_stair_edge_coverage
+    ):
+        depth_edges = detect_depth_gradient_stair_edges(
+            depth, visible_mask, args.max_step_edges
+        )
+        if depth_edges:
+            expanded = merge_edge_positions(
+                edges_y + depth_edges,
+                max(8, int(h * 0.018)),
+            )
+            expanded_coverage = stair_edge_coverage_ratio(expanded, amodal_mask)
+            if expanded_coverage > stair_edge_coverage:
+                edges_y = expanded[: args.max_step_edges]
+                stair_edge_coverage = expanded_coverage
+                edge_source = f'{edge_source} + depth-gradient expansion'
+                # Slightly lower confidence since depth-gradient edges are
+                # a secondary signal, but higher than regular fallback.
+                count_score = min(len(edges_y) / 5.0, 1.0)
+                coverage_score = min(
+                    stair_edge_coverage / max(args.minimum_auto_stair_edge_coverage, 1e-6),
+                    1.0,
+                )
+                stair_edge_confidence = float(
+                    np.clip(0.25 + 0.20 * count_score + 0.35 * coverage_score, 0.0, 0.85)
+                )
+                used_depth_gradient_edge_expansion = True
+
+    # --- Late fallback to regular fallback edges if coverage is still low ---
+    if (
+        geometry_mode == 'stairs'
+        and not args.stair_edge_y
+        and (len(edges_y) < args.minimum_detected_step_edges or stair_edge_coverage < args.minimum_auto_stair_edge_coverage)
+    ):
+        fallback = fallback_edges(amodal_mask, args.fallback_step_edges)
+        expanded = merge_edge_positions(edges_y + fallback, max(8, int(h * 0.012)))
+        expanded_coverage = stair_edge_coverage_ratio(expanded, amodal_mask)
+        if expanded_coverage > stair_edge_coverage:
+            edges_y = expanded[: args.max_step_edges]
+            stair_edge_coverage = expanded_coverage
+            edge_source = f'{edge_source} + late fallback expansion'
+            used_regular_fallback_edges = True
+            stair_edge_confidence = 0.25
+
+    fx, fy, cx, cy = camera_intrinsics(w, h, args.fx, args.fy, args.cx, args.cy)
+    if geometry_mode == 'stairs':
+        completed_depth, completion_log, confidence = complete_depth_by_planes(
+            depth,
+            completion_mask,
+            amodal_mask,
+            edges_y,
+            fx,
+            fy,
+            cx,
+            cy,
+            args.min_fit_points,
+            stair_edge_slope=stair_edge_slope,
+        )
+        if used_regular_fallback_edges:
+            confidence[completion_mask] *= 0.45
+            completion_method = 'piecewise_stair_planes_with_low_confidence_fallback_edges'
+        else:
+            confidence[completion_mask] *= stair_edge_confidence
+            completion_method = 'piecewise_stair_planes'
+    elif geometry_mode in {'walkable', 'ramp'}:
+        completed_depth, completion_log, confidence = complete_depth_continuous_surface(
+            depth,
+            completion_mask,
+            amodal_mask,
+            fx,
+            fy,
+            cx,
+            cy,
+            args.min_fit_points,
+        )
+        completion_method = completion_log[0][3]
+    else:
+        completed_depth, completion_log, confidence = complete_depth_generic_inpaint(
+            depth, completion_mask, amodal_mask
+        )
+        completion_method = 'edge_aware_inpaint'
+
+    completed_depth = enforce_hidden_boundary_continuity(
+        completed_depth,
+        depth,
+        visible_mask,
+        completion_mask,
+        args.boundary_blend_radius,
+        args.boundary_anchor_power,
+    )
+    completed_depth, depth_correction_mask, depth_plausibility = (
+        enforce_hidden_depth_plausibility(
+            completed_depth,
+            depth,
+            visible_mask,
+            completion_mask,
+            geometry_mode,
+        )
+    )
+    confidence[depth_correction_mask] = np.minimum(
+        confidence[depth_correction_mask],
+        0.15,
+    )
+    # Completion is strictly confined to the reviewed hidden region.  The
+    # plausibility guard already enforces this; retain the assignment as a
+    # visible invariant immediately before geometry/texture export.
+    completed_depth[~completion_mask] = depth[~completion_mask]
+    completed_region = completion_mask
+    if args.completed_rgb:
+        provided_completed_rgb = read_source_grid_rgb(
+            args.completed_rgb,
+            source_shape,
+            shape,
+        )
+        clean_completed_colors = rgb.copy()
+        clean_completed_colors[completed_region] = provided_completed_rgb[completed_region]
+        color_completion_method = 'aligned_provided_rgb_completion'
+        completed_rgb_source = str(args.completed_rgb)
+    else:
+        clean_completed_colors = inpaint_rgb(rgb, completed_region, radius=5.0)
+        color_completion_method = 'opencv_telea_fallback'
+        completed_rgb_source = None
+    overlay_completed_colors = rgb.copy()
+    overlay_completed_colors[completed_region] = (
+        0.35 * overlay_completed_colors[completed_region] + 0.65 * np.array([255, 90, 30])
+    ).astype(np.uint8)
+
+    points = pixels_to_points(completed_depth, fx, fy, cx, cy)
+    valid_3d = amodal_mask & np.isfinite(completed_depth) & (completed_depth > 0)
+
+    save_mask(output_dir / 'obstacle_mask.png', obstacle_mask)
+    save_mask(output_dir / 'amodal_stair_mask.png', amodal_mask)
+    save_mask(output_dir / 'amodal_target_mask.png', amodal_mask)
+    save_mask(output_dir / 'target_visible_mask.png', visible_mask)
+    save_mask(output_dir / 'hidden_completion_mask.png', completion_mask)
+    save_mask(output_dir / 'depth_plausibility_corrections.png', depth_correction_mask)
+    save_overlay(output_dir / 'debug_overlay.png', rgb, obstacle_mask, amodal_mask, edges_y, stair_edge_slope)
+    Image.fromarray(visualize_depth(depth, valid_3d)).save(output_dir / 'input_depth_vis.png')
+    Image.fromarray(visualize_depth(completed_depth, valid_3d)).save(output_dir / 'completed_depth_vis.png')
+    hidden_depth = np.zeros_like(completed_depth, dtype=np.float32)
+    hidden_depth[completion_mask] = completed_depth[completion_mask]
+    completion_delta = np.zeros_like(completed_depth, dtype=np.float32)
+    completion_delta[completion_mask] = np.abs(completed_depth[completion_mask] - depth[completion_mask])
+    Image.fromarray(visualize_depth(completed_depth, completion_mask)).save(
+        output_dir / 'hidden_completed_depth_vis.png'
+    )
+    Image.fromarray(visualize_depth(completion_delta, completion_mask)).save(
+        output_dir / 'completion_delta_vis.png'
+    )
+    Image.fromarray(np.clip(confidence * 255.0, 0, 255).astype(np.uint8)).save(
+        output_dir / 'completion_confidence.png'
+    )
+    Image.fromarray(clean_completed_colors).save(output_dir / 'completed_rgb_inpaint.png')
+    Image.fromarray(overlay_completed_colors).save(output_dir / 'completed_region_overlay.png')
+    np.save(output_dir / 'completed_depth.npy', completed_depth.astype(np.float32))
+    np.save(output_dir / 'hidden_completed_depth.npy', hidden_depth)
+    np.save(output_dir / 'completion_delta.npy', completion_delta)
+    np.save(output_dir / 'completion_confidence.npy', confidence.astype(np.float32))
+
+    point_count = write_point_cloud_ply(output_dir / 'completed_point_cloud.ply', points, clean_completed_colors, valid_3d, args.point_stride)
+    depth_values = completed_depth[valid_3d]
+    auto_jump = max(0.03, 0.08 * float(np.percentile(depth_values, 95) - np.percentile(depth_values, 5))) if depth_values.size else 0.2
+    mesh_jump = args.max_depth_jump if args.max_depth_jump is not None else auto_jump
+    vertex_count, face_count = write_mesh_ply(
+        output_dir / 'completed_mesh.ply',
+        points,
+        clean_completed_colors,
+        valid_3d,
+        args.mesh_stride,
+        mesh_jump,
+    )
+
+    visible_unchanged = bool(np.array_equal(completed_depth[~completion_mask], depth[~completion_mask]))
+    finite_completed = bool(np.all(np.isfinite(completed_depth[amodal_mask])))
+    confidence_values = confidence[completion_mask]
+    mean_confidence = float(confidence_values.mean()) if confidence_values.size else 1.0
+    report_title = {
+        'stairs': 'Stair Geometry Completion Report',
+        'walkable': 'Walkable Surface Geometry Completion Report',
+        'ramp': 'Ramp Geometry Completion Report',
+        'generic': 'Generic Surface Geometry Completion Report',
+    }[geometry_mode]
+    report = [
+        f'# {report_title}',
+        '',
+        f'- geometry mode: `{geometry_mode}`',
+        f'- completion method: `{completion_method}`',
+        f'- image: `{args.image}`',
+        f'- reference image used for edges: `{edge_source}`',
+        f'- obstacle mask source: `{obstacle_source}`',
+        f'- amodal mask source: `{amodal_source}`',
+        f'- visible mask source: `{visible_source}`',
+        f'- depth source: `{depth_source}`',
+        f'- resolution used: `{w}x{h}`',
+        f'- intrinsics: `fx={fx:.3f}, fy={fy:.3f}, cx={cx:.3f}, cy={cy:.3f}`',
+        f'- stair edge y positions: `{edges_y}`',
+        f'- stair edge slope: `{stair_edge_slope:.6f}`',
+        f'- stair edge angle degrees: `{np.degrees(np.arctan(stair_edge_slope)):.6f}`',
+        f'- used regular fallback stair edges: `{used_regular_fallback_edges}`',
+        f'- used perspective-tolerant edge expansion: `{used_perspective_edge_expansion}`',
+        f'- used visible-mask row-gradient edge expansion: `{used_gradient_edge_expansion}`',
+        f'- stair edge confidence: `{stair_edge_confidence:.6f}`',
+        f'- stair edge vertical coverage: `{stair_edge_coverage:.6f}`',
+        f'- visible depth unchanged outside hidden region: `{visible_unchanged}`',
+        f'- completed target depth finite: `{finite_completed}`',
+        f'- boundary blend radius: `{args.boundary_blend_radius}`',
+        f'- boundary anchor power: `{args.boundary_anchor_power:.6f}`',
+        f'- mean hidden completion confidence: `{mean_confidence:.6f}`',
+        f'- depth plausibility status: `{depth_plausibility["status"]}`',
+        f'- depth plausibility candidate eligible for review: `{depth_plausibility["candidate_eligible_for_review"]}`',
+        f'- corrected implausible hidden depths: `{depth_plausibility["corrected_pixel_count"]}/{depth_plausibility["hidden_pixel_count"]}`',
+        f'- accepted observed-scale depth interval: `{depth_plausibility.get("accepted_depth_lower", "unavailable")} .. {depth_plausibility.get("accepted_depth_upper", "unavailable")}`',
+        f'- point cloud vertices: `{point_count}`',
+        f'- mesh vertices/faces: `{vertex_count}/{face_count}`',
+        '- clean RGB completion: `completed_rgb_inpaint.png`',
+        '',
+        '## Completion Regions',
+        '',
+    ]
+    for top, bottom, samples, mode in completion_log:
+        report.append(f'- y `{top}:{bottom}` visible samples `{samples}` -> `{mode}`')
+    prior_note = (
+        '- If no depth map is provided, stairs use a synthetic step prior; other modes use a continuous perspective prior. Both are debug-only.'
+    )
+    report.extend([
+        '',
+        '## Notes',
+        '',
+        prior_note,
+        '- Structured accessibility geometry constraints are written to `accessibility_geometry_analysis.json`.',
+        '- If monocular or heuristic depth is provided, the output is still relative unless calibrated metric depth is used.',
+        '- Hidden-depth plausibility limits are inferred from the observed source-depth scale; they are not metric safety thresholds.',
+        '- Replace the default obstacle box with a real suitcase/occluder mask for meaningful completion.',
+        '- For path planning, provide calibrated intrinsics and metric depth or LiDAR points; otherwise units are arbitrary.',
+    ])
+    (output_dir / 'run_report.md').write_text('\n'.join(report), encoding='utf-8')
+    analysis = build_accessibility_geometry_analysis(
+        sample_id=args.sample_id,
+        category=args.category,
+        geometry_mode=geometry_mode,
+        visible_mask=visible_mask,
+        amodal_mask=amodal_mask,
+        hidden_mask=completion_mask,
+        obstacle_mask=obstacle_mask,
+        depth=depth,
+        completed_depth=completed_depth,
+        confidence=confidence,
+        completion_method=completion_method,
+        edges_y=edges_y,
+        stair_edge_slope=stair_edge_slope,
+        edge_source=edge_source,
+        stair_edge_confidence=stair_edge_confidence,
+        stair_edge_coverage=stair_edge_coverage,
+        used_regular_fallback_edges=used_regular_fallback_edges,
+        visible_depth_unchanged=visible_unchanged,
+        completed_target_depth_finite=finite_completed,
+        point_cloud_vertices=point_count,
+        mesh_vertices=vertex_count,
+        mesh_faces=face_count,
+    )
+    analysis_path = output_dir / 'accessibility_geometry_analysis.json'
+    analysis_path.write_text(json.dumps(analysis, indent=2, ensure_ascii=False), encoding='utf-8')
+    manifest = {
+        'geometry_mode': geometry_mode,
+        'category': analysis['category'],
+        'sample_id': args.sample_id,
+        'completion_method': completion_method,
+        'color_completion_method': color_completion_method,
+        'completed_rgb_source': completed_rgb_source,
+        'completion_log': [
+            {'top': int(top), 'bottom': int(bottom), 'visible_samples': int(samples), 'mode': mode}
+            for top, bottom, samples, mode in completion_log
+        ],
+        'depth_source': depth_source,
+        'used_regular_fallback_stair_edges': used_regular_fallback_edges,
+        'used_perspective_edge_expansion': used_perspective_edge_expansion,
+        'used_gradient_edge_expansion': used_gradient_edge_expansion,
+        'used_depth_gradient_edge_expansion': used_depth_gradient_edge_expansion,
+        'stair_edge_confidence': stair_edge_confidence,
+        'stair_edge_coverage': stair_edge_coverage,
+        'stair_edges_y': edges_y,
+        'stair_edge_slope': stair_edge_slope,
+        'stair_edge_angle_degrees': float(np.degrees(np.arctan(stair_edge_slope))),
+        'visible_depth_unchanged_outside_hidden': visible_unchanged,
+        'completed_target_depth_finite': finite_completed,
+        'visible_pixel_count': int(visible_mask.sum()),
+        'amodal_pixel_count': int(amodal_mask.sum()),
+        'hidden_pixel_count': int(completion_mask.sum()),
+        'obstacle_pixel_count': int(obstacle_mask.sum()),
+        'obstacle_target_overlap_pixel_count': int((obstacle_mask & amodal_mask).sum()),
+        'obstacle_visible_overlap_ratio': float((obstacle_mask & visible_mask).sum() / max(int(visible_mask.sum()), 1)),
+        'hidden_changed_ratio': float(((np.abs(completed_depth - depth) > 1e-5) & completion_mask).sum() / max(int(completion_mask.sum()), 1)),
+        'boundary_blend_radius': args.boundary_blend_radius,
+        'boundary_anchor_power': args.boundary_anchor_power,
+        'mean_hidden_completion_confidence': mean_confidence,
+        'depth_plausibility': depth_plausibility,
+        'depth_plausibility_corrections': str(output_dir / 'depth_plausibility_corrections.png'),
+        'geometry_candidate_eligible_for_review': depth_plausibility['candidate_eligible_for_review'],
+        'point_cloud_vertices': point_count,
+        'mesh_vertices': vertex_count,
+        'mesh_faces': face_count,
+        'completed_rgb_inpaint': str(output_dir / 'completed_rgb_inpaint.png'),
+        'accessibility_geometry_analysis': str(analysis_path),
+        'depth_is_metric_truth': False,
+    }
+    (output_dir / 'geometry_manifest.json').write_text(
+        json.dumps(manifest, indent=2, ensure_ascii=False), encoding='utf-8'
+    )
+
+    print(f'Wrote outputs to {output_dir}')
+    print(f'Geometry mode: {geometry_mode}')
+    print(f'Completion method: {completion_method}')
+    print(f'Point cloud vertices: {point_count}')
+    print(f'Mesh vertices/faces: {vertex_count}/{face_count}')
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(description='Category-aware 3D amodal completion for accessibility surfaces.')
+    parser.add_argument('--image', default=None, help='Occluded RGB image (required when running reconstruction).')
+    parser.add_argument('--sample-id', default=None, help='Optional stable sample id written to JSON outputs.')
+    parser.add_argument(
+        '--category',
+        choices=['stairs', 'ramp', 'walkway', 'walkable', 'curb_cut', 'raised_curb', 'tactile_paving', 'unknown'],
+        default=None,
+        help='Accessibility target category. Defaults to the category implied by --geometry-mode.',
+    )
+    parser.add_argument('--reference-image', default=None, help='Optional clean/similar stair image used to estimate stair edge layout.')
+    parser.add_argument(
+        '--completed-rgb',
+        default=None,
+        help=(
+            'Optional display-oriented RGB completion on the exact source grid. '
+            'Only hidden target pixels are used as mesh colors; when omitted, '
+            'OpenCV Telea is retained as a debug fallback.'
+        ),
+    )
+    parser.add_argument('--depth', default=None, help='Optional depth map: .npy, .npz, 16-bit png, or grayscale image.')
+    parser.add_argument('--depth-scale', type=float, default=1.0, help='Multiplier applied to loaded depth values.')
+    parser.add_argument('--obstacle-mask', default=None, help='Binary mask of the occluding object, white/nonzero is obstacle.')
+    parser.add_argument('--amodal-mask', default=None, help='Binary mask of the full target region, including occluded area.')
+    parser.add_argument('--visible-mask', default=None, help='Reviewed visible target mask. Hidden completion is amodal minus visible.')
+    parser.add_argument(
+        '--geometry-mode',
+        choices=['stairs', 'walkable', 'ramp', 'generic'],
+        default=None,
+        help='Geometry prior. Defaults to the category-compatible mode; contradictory category/mode pairs are rejected.',
+    )
+    parser.add_argument('--occlusion-box', action='append', type=parse_box, default=[], help='Obstacle box x1,y1,x2,y2. Coordinates can be normalized or pixels. Repeatable.')
+    parser.add_argument('--no-default-obstacle', action='store_true', help='Do not use the built-in approximate suitcase box when no mask/box is given.')
+    parser.add_argument('--output-dir', default='./output/stair_geometry/', help='Output directory.')
+    parser.add_argument('--max-size', type=int, default=1280, help='Resize longest image side before processing. Use 0 to keep original size.')
+    parser.add_argument('--max-step-edges', type=int, default=9)
+    parser.add_argument('--fallback-step-edges', type=int, default=5)
+    parser.add_argument('--minimum-detected-step-edges', type=int, default=2)
+    parser.add_argument('--minimum-auto-stair-edge-coverage', type=float, default=0.35)
+    parser.add_argument('--stair-edge-y', action='append', type=int, default=[], help='Reviewed stair tread-edge y coordinate. Repeatable; disables regular fallback edges.')
+    parser.add_argument('--stair-edge-angle-degrees', type=float, default=0.0, help='Reviewed tread-edge angle for --stair-edge-y; 0 means horizontal.')
+    parser.add_argument('--synthetic-near', type=float, default=1.0)
+    parser.add_argument('--synthetic-far', type=float, default=6.0)
+    parser.add_argument('--fx', type=float, default=None)
+    parser.add_argument('--fy', type=float, default=None)
+    parser.add_argument('--cx', type=float, default=None)
+    parser.add_argument('--cy', type=float, default=None)
+    parser.add_argument('--min-fit-points', type=int, default=800)
+    parser.add_argument('--boundary-blend-radius', type=int, default=12)
+    parser.add_argument(
+        '--boundary-anchor-power',
+        type=float,
+        default=0.45,
+        help='Power applied to hidden-boundary anchoring weights; lower values preserve visible-depth continuity over a wider band.',
+    )
+    parser.add_argument('--point-stride', type=int, default=3)
+    parser.add_argument('--mesh-stride', type=int, default=5)
+    parser.add_argument('--max-depth-jump', type=float, default=None, help='Max depth discontinuity allowed when making mesh faces.')
+    return parser
+
+
+if __name__ == '__main__':
+    args = build_parser().parse_args()
+    if args.max_size == 0:
+        args.max_size = None
+    run(args)

accessibilityamodal/sam_refinement.py

@@ -0,0 +1,173 @@
+"""Refine coarse target/obstacle masks with Segment Anything box prompts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps
+
+
+def read_rgb(path: str | Path) -> np.ndarray:
+    return np.array(ImageOps.exif_transpose(Image.open(path)).convert('RGB'))
+
+
+def read_mask(path: str | Path, shape: tuple[int, int]) -> np.ndarray:
+    mask = np.array(ImageOps.exif_transpose(Image.open(path)).convert('L')) > 127
+    h, w = shape
+    if mask.shape != (h, w):
+        raise ValueError(
+            f'Mask/RGB raster mismatch for {path}: mask={mask.shape}, rgb={(h, w)}. '
+            'Refusing to resize because this can hide EXIF-orientation misalignment.'
+        )
+    return mask
+
+
+def save_mask(path: str | Path, mask: np.ndarray) -> None:
+    Image.fromarray((mask.astype(np.uint8) * 255)).save(path)
+
+
+def component_boxes(mask: np.ndarray, keep: int, min_area: int, pad: int) -> np.ndarray:
+    num, labels, stats, _ = cv2.connectedComponentsWithStats(mask.astype(np.uint8), connectivity=8)
+    boxes = []
+    areas = []
+    h, w = mask.shape
+    for idx in range(1, num):
+        area = int(stats[idx, cv2.CC_STAT_AREA])
+        if area < min_area:
+            continue
+        x = int(stats[idx, cv2.CC_STAT_LEFT])
+        y = int(stats[idx, cv2.CC_STAT_TOP])
+        bw = int(stats[idx, cv2.CC_STAT_WIDTH])
+        bh = int(stats[idx, cv2.CC_STAT_HEIGHT])
+        boxes.append([max(0, x - pad), max(0, y - pad), min(w - 1, x + bw + pad), min(h - 1, y + bh + pad)])
+        areas.append(area)
+    if not boxes:
+        return np.empty((0, 4), dtype=np.float32)
+    order = np.argsort(np.array(areas))[::-1][:keep]
+    return np.array([boxes[i] for i in order], dtype=np.float32)
+
+
+def refine_one_mask(predictor, mask: np.ndarray, keep: int, min_area: int, pad: int) -> np.ndarray:
+    boxes = component_boxes(mask, keep=keep, min_area=min_area, pad=pad)
+    if boxes.size == 0:
+        return mask
+
+    import torch
+
+    transformed = predictor.transform.apply_boxes_torch(
+        torch.as_tensor(boxes, dtype=torch.float32, device=predictor.device),
+        mask.shape,
+    )
+    masks, scores, _ = predictor.predict_torch(
+        point_coords=None,
+        point_labels=None,
+        boxes=transformed,
+        multimask_output=True,
+    )
+
+    refined = np.zeros_like(mask, dtype=bool)
+    masks_np = masks.detach().cpu().numpy()
+    scores_np = scores.detach().cpu().numpy()
+    for i in range(masks_np.shape[0]):
+        best = int(np.argmax(scores_np[i]))
+        refined |= masks_np[i, best].astype(bool)
+    return refined
+
+
+def overlay(rgb: np.ndarray, masks: list[tuple[np.ndarray, tuple[int, int, int], float]]) -> np.ndarray:
+    out = rgb.astype(np.float32).copy()
+    for mask, color, alpha in masks:
+        if mask.any():
+            out[mask] = out[mask] * (1.0 - alpha) + np.array(color, dtype=np.float32) * alpha
+    return np.clip(out, 0, 255).astype(np.uint8)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description='Refine binary masks with SAM using mask-derived box prompts.')
+    parser.add_argument('--image', required=True)
+    parser.add_argument('--target-mask', required=True)
+    parser.add_argument('--obstacle-mask', required=True)
+    parser.add_argument('--output-dir', required=True)
+    parser.add_argument('--sam-repo', default='../amodal/segment-anything', help='Path containing the segment_anything package.')
+    parser.add_argument('--sam-checkpoint', required=True)
+    parser.add_argument('--sam-model-type', choices=['vit_h', 'vit_l', 'vit_b', 'default'], default='vit_h')
+    parser.add_argument('--device', default='auto')
+    parser.add_argument('--keep-target-components', type=int, default=8)
+    parser.add_argument('--keep-obstacle-components', type=int, default=4)
+    parser.add_argument('--min-area', type=int, default=64)
+    return parser
+
+
+def main() -> None:
+    args = build_parser().parse_args()
+    rgb = read_rgb(args.image)
+    shape = rgb.shape[:2]
+    target = read_mask(args.target_mask, shape)
+    obstacle = read_mask(args.obstacle_mask, shape)
+
+    sam_repo = Path(args.sam_repo).resolve()
+    checkpoint = Path(args.sam_checkpoint).resolve()
+    if not checkpoint.exists():
+        raise FileNotFoundError(f'SAM checkpoint not found: {checkpoint}')
+    if not sam_repo.exists():
+        raise FileNotFoundError(f'SAM repo not found: {sam_repo}')
+
+    sys.path.insert(0, str(sam_repo))
+    import torch
+    from segment_anything import SamPredictor, sam_model_registry
+
+    if args.device == 'auto':
+        device = 'cuda' if torch.cuda.is_available() else 'cpu'
+    else:
+        device = args.device
+    sam = sam_model_registry[args.sam_model_type](checkpoint=str(checkpoint)).to(device=device)
+    predictor = SamPredictor(sam)
+    predictor.set_image(rgb)
+
+    refined_target = refine_one_mask(
+        predictor,
+        target,
+        keep=args.keep_target_components,
+        min_area=args.min_area,
+        pad=args.box_pad,
+    )
+    refined_obstacle = refine_one_mask(
+        predictor,
+        obstacle,
+        keep=args.keep_obstacle_components,
+        min_area=args.min_area,
+        pad=args.box_pad,
+    )
+
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    target_path = output_dir / 'target_visible_mask_sam.png'
+    obstacle_path = output_dir / 'obstacle_mask_sam.png'
+    overlay_path = output_dir / 'sam_refine_overlay.png'
+    manifest_path = output_dir / 'sam_refine_manifest.json'
+    save_mask(target_path, refined_target)
+    save_mask(obstacle_path, refined_obstacle)
+    Image.fromarray(overlay(rgb, [
+        (refined_target, (0, 220, 80), 0.45),
+        (refined_obstacle, (255, 60, 20), 0.55),
+    ])).save(overlay_path)
+    manifest_path.write_text(json.dumps({
+        'image': args.image,
+        'sam_repo': str(sam_repo),
+        'sam_checkpoint': str(checkpoint),
+        'sam_model_type': args.sam_model_type,
+        'device': device,
+        'target_output': str(target_path),
+        'obstacle_output': str(obstacle_path),
+        'overlay': str(overlay_path),
+    }, indent=2), encoding='utf-8')
+    print(f'Wrote SAM-refined masks to {output_dir}')
+
+
+if __name__ == '__main__':
+    main()

accessibilityamodal/verification.py

@@ -0,0 +1,764 @@
+"""Auditable quality gates for accessibility 3D completion candidates.
+
+This module deliberately records compact, inspectable evidence instead of
+using an opaque free-form reasoning step.  It is a *reconstruction quality*
+gate, not a certification of accessibility, safety, or metric navigation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+DECISION_ORDER = {"accept": 0, "manual_review": 1, "reject": 2}
+
+
+CATEGORY_POLICIES: dict[str, dict[str, float]] = {
+    "stairs": {
+        "min_visible_image_ratio": 0.008,
+        "min_visible_amodal_ratio": 0.15,
+        "max_hidden_visible_ratio": 4.0,
+        "max_hidden_amodal_ratio": 0.75,
+        "max_obstacle_amodal_ratio": 0.75,
+    },
+    "ramp": {
+        "min_visible_image_ratio": 0.006,
+        "min_visible_amodal_ratio": 0.12,
+        "max_hidden_visible_ratio": 3.5,
+        "max_hidden_amodal_ratio": 0.72,
+        "max_obstacle_amodal_ratio": 0.72,
+    },
+    "walkway": {
+        "min_visible_image_ratio": 0.008,
+        "min_visible_amodal_ratio": 0.12,
+        "max_hidden_visible_ratio": 3.5,
+        "max_hidden_amodal_ratio": 0.72,
+        "max_obstacle_amodal_ratio": 0.72,
+    },
+    "curb_cut": {
+        "min_visible_image_ratio": 0.004,
+        "min_visible_amodal_ratio": 0.10,
+        "max_hidden_visible_ratio": 3.0,
+        "max_hidden_amodal_ratio": 0.70,
+        "max_obstacle_amodal_ratio": 0.70,
+    },
+    "tactile_paving": {
+        "min_visible_image_ratio": 0.002,
+        "min_visible_amodal_ratio": 0.10,
+        "max_hidden_visible_ratio": 3.0,
+        "max_hidden_amodal_ratio": 0.70,
+        "max_obstacle_amodal_ratio": 0.70,
+    },
+}
+
+
+def _round(value: float, digits: int = 6) -> float:
+    return round(float(value), digits)
+
+
+def _ratio(numerator: int | float, denominator: int | float) -> float:
+    return float(numerator) / float(denominator) if denominator else 0.0
+
+
+def _policy(category: str) -> dict[str, float]:
+    return CATEGORY_POLICIES.get(category, CATEGORY_POLICIES["walkway"])
+
+
+def _component_stats(mask: np.ndarray) -> dict[str, Any]:
+    count, _, stats, _ = cv2.connectedComponentsWithStats(mask.astype(np.uint8), 8)
+    areas = stats[1:, cv2.CC_STAT_AREA] if count > 1 else np.empty((0,), dtype=np.int32)
+    total = int(mask.sum())
+    largest = int(areas.max()) if areas.size else 0
+    return {
+        "component_count": int(len(areas)),
+        "largest_component_pixels": largest,
+        "largest_component_fraction": _round(_ratio(largest, total)),
+    }
+
+
+def _trace(
+    rule_id: str,
+    decision: str,
+    observed: Any,
+    expected: Any,
+    explanation: str,
+) -> dict[str, Any]:
+    return {
+        "rule_id": rule_id,
+        "decision": decision,
+        "observed": observed,
+        "expected": expected,
+        "explanation": explanation,
+    }
+
+
+def _worst_decision(*decisions: str) -> str:
+    return max(decisions, key=lambda value: DECISION_ORDER[value])
+
+
+def evaluate_mask_preflight(
+    *,
+    category: str,
+    visible_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    hidden_mask: np.ndarray,
+    obstacle_mask: np.ndarray,
+    sam3_quality: dict[str, Any] | None = None,
+    reviewed_visible_metadata: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Evaluate whether masks have enough observed support for automatic 3D."""
+    policy = _policy(category)
+    input_shapes = {
+        "visible": list(visible_mask.shape),
+        "amodal": list(amodal_mask.shape),
+        "hidden": list(hidden_mask.shape),
+        "obstacle": list(obstacle_mask.shape),
+    }
+    if not (
+        visible_mask.shape == amodal_mask.shape == hidden_mask.shape == obstacle_mask.shape
+    ):
+        return {
+            "decision": "reject",
+            "policy": policy,
+            "measurements": {"input_mask_shapes": input_shapes},
+            "audit_trace": [
+                _trace(
+                    "mask_shape_consistency",
+                    "reject",
+                    input_shapes,
+                    "all masks have exactly the same HxW shape",
+                    "A gate must not resample mismatched masks, because that can silently change the claimed visible/hidden support.",
+                )
+            ],
+        }
+    image_area = int(visible_mask.size)
+    visible_pixels = int(visible_mask.sum())
+    amodal_pixels = int(amodal_mask.sum())
+    hidden_pixels = int(hidden_mask.sum())
+    obstacle_pixels = int(obstacle_mask.sum())
+    obstacle_amodal_pixels = int((obstacle_mask & amodal_mask).sum())
+    visible_amodal_ratio = _ratio(visible_pixels, amodal_pixels)
+    hidden_visible_ratio = _ratio(hidden_pixels, max(visible_pixels, 1))
+    hidden_amodal_ratio = _ratio(hidden_pixels, amodal_pixels)
+    obstacle_amodal_ratio = _ratio(obstacle_amodal_pixels, amodal_pixels)
+    trace: list[dict[str, Any]] = []
+
+    sam_status = str((sam3_quality or {}).get("review_status") or "missing")
+    reviewed_visible_approved = bool(
+        reviewed_visible_metadata
+        and str(reviewed_visible_metadata.get("source_kind", "")) == "human_reviewed_visible_mask_only"
+        and str(reviewed_visible_metadata.get("review_status", "")) == "approved"
+        and bool(reviewed_visible_metadata.get("review_is_human", False))
+        and bool(reviewed_visible_metadata.get("visible_confirmed", False))
+        and str(reviewed_visible_metadata.get("annotator", "")).strip()
+    )
+    if reviewed_visible_metadata is not None:
+        trace.append(
+            _trace(
+                "reviewed_visible_mask_status",
+                "accept" if reviewed_visible_approved else "reject",
+                {
+                    "source_kind": reviewed_visible_metadata.get("source_kind"),
+                    "review_status": reviewed_visible_metadata.get("review_status"),
+                    "review_is_human": bool(reviewed_visible_metadata.get("review_is_human", False)),
+                    "visible_confirmed": bool(reviewed_visible_metadata.get("visible_confirmed", False)),
+                    "annotator_present": bool(str(reviewed_visible_metadata.get("annotator", "")).strip()),
+                },
+                "approved, human-reviewed, visible-confirmed workspace with an annotator",
+                "A reviewed visible boundary can replace the SAM3 proposal only with explicit human approval and provenance."
+                if reviewed_visible_approved
+                else "The reviewed-visible workspace lacks the required approval provenance.",
+            )
+        )
+    if sam3_quality is not None and not reviewed_visible_approved:
+        category_verification = dict(sam3_quality.get("category_verification") or {})
+        selected_category = str(sam3_quality.get("selected_category") or "")
+        best_category = str(category_verification.get("best_scored_category") or "")
+        category_disagreement = bool(category_verification.get("category_disagreement", False))
+        category_ok = (
+            (not selected_category or selected_category == category)
+            and (not best_category or best_category == category)
+            and not category_disagreement
+        )
+        trace.append(
+            _trace(
+                "category_semantic_consistency",
+                "accept" if category_ok else "manual_review",
+                {
+                    "requested_category": category,
+                    "selected_category": selected_category or None,
+                    "best_scored_category": best_category or None,
+                    "category_disagreement": category_disagreement,
+                },
+                "selected and best-scored category agree with the requested category",
+                "The prompt evidence does not consistently identify the requested stairs/ramp/walkway structure; review category and support boundary."
+                if not category_ok
+                else "Prompt-category evidence is consistent with the requested support structure.",
+            )
+        )
+    if reviewed_visible_approved:
+        trace.append(
+            _trace(
+                "sam3_proposal_status",
+                "accept",
+                sam_status,
+                "recorded only; superseded by approved reviewed-visible mask",
+                "The original SAM3 proposal is retained for audit but does not override a separately approved visible target boundary.",
+            )
+        )
+    elif sam_status in {"reject_or_reprompt", "error"}:
+        trace.append(
+            _trace(
+                "sam3_review_status",
+                "reject",
+                sam_status,
+                "candidate_accept_after_visual_review or manual_review",
+                "The segmentation stage itself rejected this proposal; it must not be sent to automatic 3D generation.",
+            )
+        )
+    elif sam_status == "manual_review":
+        trace.append(
+            _trace(
+                "sam3_review_status",
+                "manual_review",
+                sam_status,
+                "candidate_accept_after_visual_review",
+                "The segmentation proposal needs human mask review before any 3D result is used.",
+            )
+        )
+    else:
+        trace.append(
+            _trace(
+                "sam3_review_status",
+                "accept" if sam_status == "candidate_accept_after_visual_review" else "manual_review",
+                sam_status,
+                "candidate_accept_after_visual_review",
+                "SAM3 status is recorded as evidence; automatic masks remain proposals rather than ground truth.",
+            )
+        )
+
+    visible_image_ratio = _ratio(visible_pixels, image_area)
+    for rule_id, observed, threshold, comparator, explanation in (
+        (
+            "minimum_observed_support",
+            visible_image_ratio,
+            policy["min_visible_image_ratio"],
+            ">=",
+            "The observed target footprint is too small to support a stable scene-level reconstruction.",
+        ),
+        (
+            "visible_over_amodal_support",
+            visible_amodal_ratio,
+            policy["min_visible_amodal_ratio"],
+            ">=",
+            "Most of the alleged support is hidden, so the completion would be driven by hallucinated geometry rather than observed structure.",
+        ),
+        (
+            "hidden_over_visible_support",
+            hidden_visible_ratio,
+            policy["max_hidden_visible_ratio"],
+            "<=",
+            "The hidden region is disproportionate to observed support and commonly indicates wall/railing leakage into the amodal mask.",
+        ),
+        (
+            "hidden_over_amodal_support",
+            hidden_amodal_ratio,
+            policy["max_hidden_amodal_ratio"],
+            "<=",
+            "Automatic 3D must retain enough visible surface evidence rather than invent nearly the whole target.",
+        ),
+        (
+            "obstacle_dominates_target",
+            obstacle_amodal_ratio,
+            policy["max_obstacle_amodal_ratio"],
+            "<=",
+            "An obstacle that occupies most of the alleged target is likely a side wall, railing, or segmentation leak rather than a compact occluder.",
+        ),
+    ):
+        passed = observed >= threshold if comparator == ">=" else observed <= threshold
+        trace.append(
+            _trace(
+                rule_id,
+                "accept" if passed else "reject",
+                _round(observed),
+                f"{comparator} {_round(threshold)}",
+                "Observed support satisfies the guard." if passed else explanation,
+            )
+        )
+
+    components = _component_stats(visible_mask)
+    fragmented = (
+        components["component_count"] >= 8
+        and components["largest_component_fraction"] < 0.35
+    )
+    trace.append(
+        _trace(
+            "visible_support_connectedness",
+            "manual_review" if fragmented else "accept",
+            components,
+            "largest component >= 35% when >= 8 components",
+            "Fragmented stair treads can be valid, but need a reviewed support boundary before surface completion."
+            if fragmented
+            else "Observed support is sufficiently connected for automatic processing.",
+        )
+    )
+
+    decision = _worst_decision(*(row["decision"] for row in trace))
+    return {
+        "decision": decision,
+        "policy": policy,
+        "measurements": {
+            "image_pixels": image_area,
+            "visible_pixels": visible_pixels,
+            "amodal_pixels": amodal_pixels,
+            "hidden_pixels": hidden_pixels,
+            "obstacle_pixels": obstacle_pixels,
+            "visible_image_ratio": _round(visible_image_ratio),
+            "visible_amodal_ratio": _round(visible_amodal_ratio),
+            "hidden_visible_ratio": _round(hidden_visible_ratio),
+            "hidden_amodal_ratio": _round(hidden_amodal_ratio),
+            "obstacle_amodal_ratio": _round(obstacle_amodal_ratio),
+            **components,
+        },
+        "audit_trace": trace,
+    }
+
+
+def evaluate_geometry_structure(
+    category: str,
+    geometry_manifest: dict[str, Any] | None,
+) -> dict[str, Any]:
+    """Check deterministic evidence emitted by accessibilityamodal.reconstruct."""
+    if not geometry_manifest:
+        return {
+            "decision": "manual_review",
+            "measurements": {},
+            "audit_trace": [
+                _trace(
+                    "geometry_manifest_present",
+                    "manual_review",
+                    False,
+                    True,
+                    "No deterministic geometry manifest is available yet.",
+                )
+            ],
+        }
+    trace: list[dict[str, Any]] = []
+    expected_mode = {
+        "stairs": "stairs",
+        "ramp": "ramp",
+        "walkway": "walkable",
+        "curb_cut": "walkable",
+        "tactile_paving": "walkable",
+    }.get(category)
+    observed_mode = str(geometry_manifest.get("geometry_mode") or "")
+    trace.append(
+        _trace(
+            "geometry_category_mode_consistency",
+            "accept" if observed_mode == expected_mode else "manual_review",
+            {"requested_category": category, "geometry_mode": observed_mode or None},
+            f"geometry_mode={expected_mode}",
+            "The deterministic geometry branch does not match the requested accessibility structure."
+            if observed_mode != expected_mode
+            else "The deterministic geometry branch matches the requested structure.",
+        )
+    )
+    log = list(geometry_manifest.get("completion_log") or [])
+    plane_bands = sum(
+        1 for row in log if str(row.get("mode") or "").startswith("plane")
+    )
+    fallback_bands = sum(
+        1 for row in log if "fallback" in str(row.get("mode") or ""))
+    fallback_ratio = _ratio(fallback_bands, max(len(log), 1))
+    trace.append(
+        _trace(
+            "completion_band_support",
+            "reject" if fallback_ratio > 0.25 else "accept",
+            {"band_count": len(log), "plane_bands": plane_bands, "fallback_bands": fallback_bands, "fallback_ratio": _round(fallback_ratio)},
+            "fallback_ratio <= 0.25",
+            "Too many stair bands lacked observed points and fell back to image inpainting."
+            if fallback_ratio > 0.25
+            else "Most completion bands are supported by fitted geometry.",
+        )
+    )
+    hidden_pixels = int(geometry_manifest.get("hidden_pixel_count") or 0)
+    confidence = float(geometry_manifest.get("mean_hidden_completion_confidence") or 0.0)
+    hidden_confidence_decision = "accept" if hidden_pixels == 0 else "manual_review" if confidence < 0.50 else "accept"
+    trace.append(
+        _trace(
+            "hidden_geometry_confidence",
+            hidden_confidence_decision,
+            "not_applicable_no_hidden_region" if hidden_pixels == 0 else _round(confidence),
+            "not applicable when hidden_pixel_count=0; otherwise >= 0.50",
+            "No target surface was extrapolated, so hidden-depth confidence is not applicable."
+            if hidden_pixels == 0
+            else "Hidden depth confidence is low; do not treat the result as a publishable or navigation-ready surface."
+            if hidden_confidence_decision == "manual_review"
+            else "Hidden completion confidence meets the local visualization threshold.",
+        )
+    )
+    faces = int(geometry_manifest.get("mesh_faces") or 0)
+    trace.append(
+        _trace(
+            "mesh_nonempty",
+            "reject" if faces <= 0 else "accept",
+            faces,
+            "> 0",
+            "No mesh faces were produced." if faces <= 0 else "Mesh contains triangle faces.",
+        )
+    )
+    if category == "stairs":
+        edges = list(geometry_manifest.get("stair_edges_y") or [])
+        edge_confidence = float(geometry_manifest.get("stair_edge_confidence") or 0.0)
+        trace.append(
+            _trace(
+                "stair_repetition_evidence",
+                "manual_review" if len(edges) < 3 or edge_confidence < 0.45 else "accept",
+                {"edge_count": len(edges), "edge_confidence": _round(edge_confidence), "edge_slope": _round(float(geometry_manifest.get("stair_edge_slope") or 0.0))},
+                "at least 3 edges and confidence >= 0.45",
+                "Too little repeated tread evidence is available for a reliable stair regularization."
+                if len(edges) < 3 or edge_confidence < 0.45
+                else "Repeated stair-edge evidence supports a segmented stair prior.",
+            )
+        )
+    decision = _worst_decision(*(row["decision"] for row in trace))
+    return {
+        "decision": decision,
+        "measurements": {
+            "completion_band_count": len(log),
+            "plane_band_count": plane_bands,
+            "fallback_band_count": fallback_bands,
+            "fallback_band_ratio": _round(fallback_ratio),
+            "hidden_pixel_count": hidden_pixels,
+            "mean_hidden_completion_confidence": _round(confidence),
+            "mesh_faces": faces,
+        },
+        "audit_trace": trace,
+    }
+
+
+def _foreground_measurement(path: Path) -> dict[str, float]:
+    image = np.asarray(Image.open(path).convert("RGB"))
+    foreground = np.any(image < 245, axis=2)
+    ys, xs = np.where(foreground)
+    if xs.size == 0:
+        return {"coverage": 0.0, "bbox_width_ratio": 0.0, "bbox_height_ratio": 0.0, "bbox_aspect_ratio": 0.0}
+    width_ratio = _ratio(int(xs.max() - xs.min() + 1), image.shape[1])
+    height_ratio = _ratio(int(ys.max() - ys.min() + 1), image.shape[0])
+    return {
+        "coverage": _round(float(foreground.mean())),
+        "bbox_width_ratio": _round(width_ratio),
+        "bbox_height_ratio": _round(height_ratio),
+        "bbox_aspect_ratio": _round(min(width_ratio, height_ratio) / max(width_ratio, height_ratio, 1e-6)),
+    }
+
+
+def evaluate_full_gpu_render_contract(learned_dir: Path) -> dict[str, Any]:
+    """Require evidence that both learned representations were rasterized on CUDA."""
+
+    manifest_path = learned_dir / "manifest.json"
+    required_files = (
+        "sample_gaussian.gif",
+        "sample_mesh.gif",
+        "sample_multi.gif",
+        "multiview_contact_sheet.jpg",
+        "mesh.ply",
+    )
+    missing_files = [
+        name
+        for name in required_files
+        if not (learned_dir / name).is_file()
+        or (learned_dir / name).stat().st_size <= 0
+    ]
+    payload: dict[str, Any] = {}
+    manifest_error = None
+    try:
+        value = json.loads(manifest_path.read_text(encoding="utf-8"))
+        if not isinstance(value, dict):
+            raise ValueError("manifest root is not an object")
+        payload = value
+    except Exception as exc:
+        manifest_error = f"{type(exc).__name__}: {exc}"
+
+    renderer = payload.get("gpu_renderer_runtime")
+    validation = payload.get("render_validation")
+    gaussian = renderer.get("gaussian") if isinstance(renderer, dict) else None
+    dense_mesh = (
+        renderer.get("dense_mesh") if isinstance(renderer, dict) else None
+    )
+    nviews = int(payload.get("nviews") or 0)
+    gaussian_views = sorted(learned_dir.glob("*_gs.png"))
+    mesh_views = sorted(learned_dir.glob("*_mesh.png"))
+    contract_ok = (
+        manifest_error is None
+        and not missing_files
+        and isinstance(renderer, dict)
+        and isinstance(gaussian, dict)
+        and gaussian.get("available") is True
+        and gaussian.get("required") is True
+        and gaussian.get("device") == "cuda"
+        and gaussian.get("runtime_import_succeeded") is True
+        and isinstance(dense_mesh, dict)
+        and dense_mesh.get("available") is True
+        and dense_mesh.get("required") is True
+        and dense_mesh.get("device") == "cuda"
+        and dense_mesh.get("runtime_import_succeeded") is True
+        and dense_mesh.get("cuda_context_preflight_succeeded") is True
+        and renderer.get("cpu_render_fallback_allowed") is False
+        and renderer.get("gaussian_only_debug_mode") is False
+        and isinstance(validation, dict)
+        and validation.get("validated") is True
+        and validation.get("dense_mesh_rendered_on_gpu") is True
+        and validation.get("cpu_render_fallback_used") is False
+        and int(validation.get("mesh_face_count") or 0) > 0
+        and nviews > 0
+        and len(gaussian_views) == nviews
+        and len(mesh_views) == nviews
+    )
+    return {
+        "decision": "accept" if contract_ok else "reject",
+        "measurements": {
+            "manifest_error": manifest_error,
+            "missing_files": missing_files,
+            "declared_view_count": nviews,
+            "gaussian_view_count": len(gaussian_views),
+            "mesh_view_count": len(mesh_views),
+            "gaussian_cuda": bool(
+                isinstance(gaussian, dict)
+                and gaussian.get("device") == "cuda"
+            ),
+            "dense_mesh_cuda": bool(
+                isinstance(dense_mesh, dict)
+                and dense_mesh.get("device") == "cuda"
+            ),
+            "cpu_render_fallback_used": (
+                validation.get("cpu_render_fallback_used")
+                if isinstance(validation, dict)
+                else None
+            ),
+        },
+        "audit_trace": [
+            _trace(
+                "full_gpu_renderer_contract",
+                "accept" if contract_ok else "reject",
+                {
+                    "manifest_present": manifest_path.is_file(),
+                    "missing_files": missing_files,
+                    "gaussian_views": len(gaussian_views),
+                    "mesh_views": len(mesh_views),
+                    "declared_views": nviews,
+                },
+                "CUDA Gaussian and nvdiffrast mesh renders, no CPU fallback",
+                (
+                    "The learned result proves both CUDA render paths and a "
+                    "validated dense triangle mesh."
+                    if contract_ok
+                    else "The learned result is incomplete or does not prove the required CUDA Gaussian + dense-mesh render contract."
+                ),
+            )
+        ],
+    }
+
+
+def evaluate_learned_multiview(
+    category: str,
+    learned_dir: Path | None,
+) -> dict[str, Any]:
+    """Check learned visual candidates without treating renderer coordinates as metric geometry."""
+    if learned_dir is None or not learned_dir.is_dir():
+        return {
+            "decision": "manual_review",
+            "measurements": {},
+            "audit_trace": [
+                _trace("learned_multiview_present", "manual_review", False, True, "No learned Accessibility3D multiview result is available.")
+            ],
+        }
+    views = sorted(learned_dir.glob("*_gs.png"))
+    if not views:
+        return {
+            "decision": "reject",
+            "measurements": {},
+            "audit_trace": [
+                _trace("learned_multiview_present", "reject", False, True, "The learned 3D result has no rendered multiview evidence.")
+            ],
+        }
+    measures = [_foreground_measurement(path) for path in views]
+    gpu_contract = evaluate_full_gpu_render_contract(learned_dir)
+    median_coverage = float(np.median([row["coverage"] for row in measures]))
+    median_aspect = float(np.median([row["bbox_aspect_ratio"] for row in measures]))
+    coverage_decision = (
+        "reject" if median_coverage < 0.05 else "manual_review" if median_coverage < 0.12 else "accept"
+    )
+    aspect_decision = (
+        "reject" if median_aspect < 0.10 else "manual_review" if median_aspect < 0.30 else "accept"
+    )
+    trace = [
+        *gpu_contract["audit_trace"],
+        _trace(
+            "learned_multiview_evidence_type",
+            "accept",
+            "Gaussian-splat raster previews (*_gs.png)",
+            "visual reconstruction evidence only",
+            "These views can expose a collapsed visual candidate but do not establish physical dimensions or navigability.",
+        ),
+        _trace(
+            "multiview_foreground_coverage",
+            coverage_decision,
+            _round(median_coverage),
+            ">= 0.12",
+            "The learned object occupies almost none of the rendered views and is likely an empty or fragmentary result."
+            if coverage_decision == "reject"
+            else "The object is small in the rendered views; inspect its requested scale and framing before use."
+            if coverage_decision == "manual_review"
+            else "The rendered object has adequate view coverage.",
+        ),
+        _trace(
+            "multiview_silhouette_thickness",
+            aspect_decision,
+            _round(median_aspect),
+            ">= 0.30",
+            "Most views are nearly one-dimensional, which is inconsistent with a usable support-surface candidate."
+            if aspect_decision == "reject"
+            else "The views are elongated; this can be valid for a long ramp or stair flight, but needs human geometry review."
+            if aspect_decision == "manual_review"
+            else "Rendered silhouettes have a plausible two-dimensional extent.",
+        ),
+    ]
+    mesh_measurements: dict[str, Any] = {}
+    mesh_path = learned_dir / "mesh.ply"
+    if mesh_path.is_file():
+        try:
+            import trimesh
+
+            mesh = trimesh.load(mesh_path, process=False)
+            extent = np.asarray(mesh.bounds[1] - mesh.bounds[0], dtype=np.float64)
+            minmax_ratio = float(extent.min() / max(float(extent.max()), 1e-6))
+            mesh_measurements = {
+                "vertices": int(len(mesh.vertices)),
+                "faces": int(len(mesh.faces)),
+                "extent": [_round(value) for value in extent],
+                "minmax_extent_ratio": _round(minmax_ratio),
+                "watertight": bool(mesh.is_watertight),
+            }
+            extent_decision = (
+                "reject" if minmax_ratio < 0.02 else "manual_review" if minmax_ratio < 0.08 else "accept"
+            )
+            trace.append(
+                _trace(
+                    "mesh_near_degeneracy",
+                    extent_decision,
+                    _round(minmax_ratio),
+                    ">= 0.08 (manual review below); < 0.02 rejects",
+                    "The learned mesh is almost flat in its own normalized coordinates, consistent with a degenerate fragment."
+                    if extent_decision == "reject"
+                    else "The learned mesh is elongated; normalized extents alone cannot distinguish a valid long ramp/staircase from a fragment."
+                    if extent_decision == "manual_review"
+                    else "No near-zero mesh axis was detected. This is not a physical-scale check.",
+                )
+            )
+        except Exception as exc:  # pragma: no cover - optional mesh parsing
+            trace.append(_trace("mesh_near_degeneracy", "manual_review", "unavailable", ">= 0.08", f"Could not inspect learned mesh: {type(exc).__name__}"))
+    decision = _worst_decision(*(row["decision"] for row in trace))
+    return {
+        "decision": decision,
+        "measurements": {
+            "view_count": len(measures),
+            "median_foreground_coverage": _round(median_coverage),
+            "median_silhouette_aspect": _round(median_aspect),
+            "views": measures,
+            "mesh": mesh_measurements,
+            "gpu_render_contract": gpu_contract["measurements"],
+        },
+        "audit_trace": trace,
+    }
+
+
+def mobility_interpretation(category: str, decision: str) -> dict[str, Any]:
+    """Return conservative, non-metric audience-specific interpretation."""
+    withheld = decision != "accept"
+    common = "withheld pending mask/geometry review" if withheld else "requires calibrated clearance and surface survey"
+    if category == "stairs":
+        return {
+            "pedestrian": common,
+            "blind_or_low_vision_pedestrian": "requires surveyed handrail, edge, tactile, lighting, and obstacle information; monocular 3D is insufficient",
+            "wheelchair": "stairs are not an accessible route; require a separately verified ramp/lift/alternate route",
+            "robot_or_robot_dog": "requires metric riser/tread, friction, width, and local obstacle sensing; do not execute from this visual model alone",
+        }
+    return {
+        "pedestrian": common,
+        "blind_or_low_vision_pedestrian": "requires surveyed tactile/edge/obstacle information; monocular 3D is insufficient",
+        "wheelchair": common,
+        "robot_or_robot_dog": "requires metric slope, clearance, friction, and local obstacle sensing; do not execute from this visual model alone",
+    }
+
+
+def build_verification(
+    *,
+    sample_id: str,
+    category: str,
+    visible_mask: np.ndarray,
+    amodal_mask: np.ndarray,
+    hidden_mask: np.ndarray,
+    obstacle_mask: np.ndarray,
+    sam3_quality: dict[str, Any] | None = None,
+    reviewed_visible_metadata: dict[str, Any] | None = None,
+    geometry_manifest: dict[str, Any] | None = None,
+    learned_dir: Path | None = None,
+) -> dict[str, Any]:
+    """Build one JSON-ready, auditable accessibility 3D verification record."""
+    preflight = evaluate_mask_preflight(
+        category=category,
+        visible_mask=visible_mask,
+        amodal_mask=amodal_mask,
+        hidden_mask=hidden_mask,
+        obstacle_mask=obstacle_mask,
+        sam3_quality=sam3_quality,
+        reviewed_visible_metadata=reviewed_visible_metadata,
+    )
+    geometry = evaluate_geometry_structure(category, geometry_manifest)
+    learned = evaluate_learned_multiview(category, learned_dir)
+    overall = _worst_decision(preflight["decision"], geometry["decision"], learned["decision"])
+    if geometry_manifest is None and learned_dir is None:
+        overall = preflight["decision"]
+    trace = [
+        *preflight["audit_trace"],
+        *geometry["audit_trace"],
+        *learned["audit_trace"],
+    ]
+    return {
+        "schema_version": 1,
+        "sample_id": sample_id,
+        "category": category,
+        "decision": overall,
+        "gate": {
+            "allow_automatic_geometry": preflight["decision"] == "accept",
+            "allow_learned_object_3d": (
+                preflight["decision"] == "accept"
+                and geometry["decision"] == "accept"
+                and learned["decision"] == "accept"
+            ),
+            "allow_publication": False,
+            "publication_note": "Human license/privacy review and calibrated geometry validation remain required.",
+        },
+        "mask_preflight": preflight,
+        "geometry_structure": geometry,
+        "learned_multiview": learned,
+        "mobility_interpretation": mobility_interpretation(category, overall),
+        "audit_trace": trace,
+        "recommended_action": (
+            "re_prompt_or_review_masks_before_3d" if preflight["decision"] != "accept"
+            else "review_geometry_before_release" if overall != "accept"
+            else "keep_as_local_visual_candidate_not_navigation_truth"
+        ),
+        "limitations": [
+            "This is a structured reconstruction-quality gate, not chain-of-thought or a safety certification.",
+            "Monocular/depth-model geometry is not calibrated metric truth unless separately calibrated.",
+            "Do not use this record alone to control a pedestrian aid, wheelchair, robot, or robot dog.",
+        ],
+    }

accessibilityamodal/visual_completion.py

@@ -0,0 +1,493 @@
+"""Mask policy, prompts, and quality gates for visual accessibility completion.
+
+The geometry target and the visual removal region have deliberately different
+roles.  ``hidden`` remains the geometry target.  For visual inpainting, an
+entire foreground obstacle instance is removed when any pixel in its
+8-connected component intersects ``hidden``.  Nearby people or objects that do
+not intersect ``hidden`` remain untouched.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any
+
+import cv2
+import numpy as np
+from PIL import Image
+
+
+PROMPTS = {
+    "stairs": (
+        "photorealistic continuation of the same staircase behind the removed foreground "
+        "occluder, continuous stair treads aligned with the visible steps, same perspective, "
+        "same material and texture, same lighting and exposure, empty completed surface"
+    ),
+    "ramp": (
+        "photorealistic continuation of the same accessible ramp behind the removed foreground "
+        "occluder, continuous sloped walking surface, same perspective, same material and "
+        "texture, same lighting and exposure, empty completed surface"
+    ),
+    "curb_cut": (
+        "photorealistic continuation of the same curb cut and pavement transition behind the "
+        "removed foreground occluder, same perspective, same material and texture, same lighting "
+        "and exposure, continuous empty completed surface"
+    ),
+    "raised_curb": (
+        "photorealistic continuation of the same raised curb behind the removed foreground "
+        "occluder, one continuous level curb top and straight curb face, same perspective, "
+        "same material and texture, same lighting and exposure, no added steps"
+    ),
+    "tactile_paving": (
+        "photorealistic continuation of the same tactile paving path behind the removed "
+        "foreground occluder, regularly aligned tactile pattern, same perspective, same material "
+        "and texture, same lighting and exposure, continuous empty completed surface"
+    ),
+    "walkway": (
+        "photorealistic continuation of the same accessible pedestrian walkway behind the "
+        "removed foreground occluder, continuous walking surface, same perspective, same material "
+        "and texture, same lighting and exposure, empty completed surface"
+    ),
+}
+
+NEGATIVE_PROMPT = (
+    "person, human, legs, pedestrian, bicycle, wheel, wheelchair, stroller, walker, cart, "
+    "luggage, bag, backpack, cane, obstacle, vehicle, animal, fog, haze, blur, melted "
+    "geometry, warped stairs, broken steps, duplicate steps, misaligned edges, text, "
+    "watermark, illustration"
+)
+
+FOG_HAZE_MAX_SHARPNESS_RATIO = 0.65
+FOG_HAZE_MAX_CONTRAST_RATIO = 0.85
+OVER_SHARP_MIN_SHARPNESS_RATIO = 1.9
+OVER_SHARP_MIN_SEAM_PENALTY = 1.45
+
+
+def _binary_array(mask: np.ndarray, name: str) -> np.ndarray:
+    array = np.asarray(mask)
+    if array.ndim != 2:
+        raise ValueError(f"{name} must be a 2D mask, got shape={array.shape}")
+    return array.astype(bool, copy=False)
+
+
+def derive_hidden_mask(target_amodal: np.ndarray, target_visible: np.ndarray) -> np.ndarray:
+    """Derive the geometry hidden target without changing either input mask."""
+
+    amodal = _binary_array(target_amodal, "target_amodal")
+    visible = _binary_array(target_visible, "target_visible")
+    if amodal.shape != visible.shape:
+        raise ValueError("Target amodal and visible masks must have the same shape")
+    return amodal & ~visible
+
+
+def mask_statistics(mask: np.ndarray) -> dict[str, int | float]:
+    """Return path-free mask statistics suitable for a portable manifest."""
+
+    binary = _binary_array(mask, "mask")
+    height, width = binary.shape
+    pixels = int(binary.sum())
+    image_pixels = int(binary.size)
+    return {
+        "width": int(width),
+        "height": int(height),
+        "image_pixels": image_pixels,
+        "pixel_count": pixels,
+        "image_fraction": round(pixels / image_pixels, 8) if image_pixels else 0.0,
+    }
+
+
+def _retain_components_occluding_hidden(
+    detected_obstacles: np.ndarray,
+    hidden: np.ndarray,
+) -> tuple[np.ndarray, int, int]:
+    """Equivalent policy to filter_accessibility_occluding_obstacles."""
+
+    if detected_obstacles.shape != hidden.shape:
+        raise ValueError("Obstacle and hidden masks must have the same shape")
+    count, labels = cv2.connectedComponents(
+        detected_obstacles.astype(np.uint8),
+        connectivity=8,
+    )
+    keep_labels = np.unique(labels[hidden & detected_obstacles])
+    keep_labels = keep_labels[keep_labels != 0]
+    return np.isin(labels, keep_labels), int(count - 1), int(len(keep_labels))
+
+
+def build_visual_removal_mask(
+    hidden: np.ndarray,
+    obstacle: np.ndarray | None = None,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """Build the visual inpaint mask while preserving ``hidden`` for geometry.
+
+    When ``obstacle`` is omitted, the returned visual mask is exactly ``hidden``
+    for backward compatibility.
+    """
+
+    geometry_hidden = _binary_array(hidden, "hidden")
+    if obstacle is None:
+        detected = np.zeros_like(geometry_hidden)
+        retained = np.zeros_like(geometry_hidden)
+        before_components = 0
+        retained_components = 0
+    else:
+        detected = _binary_array(obstacle, "obstacle")
+        if detected.shape != geometry_hidden.shape:
+            raise ValueError("Obstacle and hidden masks must have the same shape")
+        retained, before_components, retained_components = (
+            _retain_components_occluding_hidden(detected, geometry_hidden)
+        )
+
+    visual_removal = geometry_hidden | retained
+    stats = {
+        "policy": (
+            "hidden_union_full_8_connected_obstacle_components_intersecting_hidden"
+            if obstacle is not None
+            else "legacy_hidden_only"
+        ),
+        "obstacle_mask_provided": obstacle is not None,
+        "geometry_hidden_unchanged": True,
+        "geometry_hidden": mask_statistics(geometry_hidden),
+        "obstacle_input": mask_statistics(detected),
+        "obstacle_components_input": before_components,
+        "obstacle_retained": mask_statistics(retained),
+        "obstacle_components_retained": retained_components,
+        "non_occluding_obstacle_pixels_excluded": int((detected & ~retained).sum()),
+        "visual_removal": mask_statistics(visual_removal),
+        "visual_extra_pixels_beyond_hidden": int((visual_removal & ~geometry_hidden).sum()),
+    }
+    return visual_removal, stats
+
+
+def build_completion_envelope(
+    visual_removal: np.ndarray,
+    obstacle: np.ndarray | None,
+    *,
+    margin_fraction: float = 0.022,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """Fill retained foreground-instance boxes before generative completion.
+
+    A person mask often excludes a carried bag, walker, bicycle frame, or the
+    small gaps between limbs.  Inpainting only the segmentation silhouette can
+    therefore preserve or regenerate those objects.  This appearance-only mask
+    fills the bounding box of each retained obstacle component and adds a small
+    image-relative margin.  Geometry continues to use the unchanged hidden
+    target; non-occluding obstacle pixels are protected by the caller.
+    """
+
+    removal = _binary_array(visual_removal, "visual_removal")
+    if margin_fraction < 0:
+        raise ValueError("margin_fraction must be non-negative")
+    if obstacle is None:
+        return removal.copy(), {
+            "policy": "visual_removal_without_obstacle_envelope",
+            "component_count": 0,
+            "margin_pixels": 0,
+            "extra_pixels": 0,
+            "completion_envelope": mask_statistics(removal),
+        }
+
+    detected = _binary_array(obstacle, "obstacle")
+    if detected.shape != removal.shape:
+        raise ValueError("Obstacle and visual removal masks must have the same shape")
+    retained_obstacle = detected & removal
+    count, labels, stats, _ = cv2.connectedComponentsWithStats(
+        retained_obstacle.astype(np.uint8),
+        connectivity=8,
+    )
+    height, width = removal.shape
+    margin = int(round(min(height, width) * margin_fraction))
+    envelope = removal.copy()
+    boxes: list[dict[str, int]] = []
+    for label in range(1, count):
+        x, y, box_width, box_height, area = (
+            int(value) for value in stats[label]
+        )
+        if area <= 0:
+            continue
+        x1 = max(0, x - margin)
+        y1 = max(0, y - margin)
+        x2 = min(width, x + box_width + margin)
+        y2 = min(height, y + box_height + margin)
+        envelope[y1:y2, x1:x2] = True
+        boxes.append(
+            {
+                "x1": x1,
+                "y1": y1,
+                "x2": x2,
+                "y2": y2,
+                "source_component_pixels": area,
+            }
+        )
+    return envelope, {
+        "policy": "retained_obstacle_component_bounding_envelopes",
+        "component_count": len(boxes),
+        "margin_pixels": margin,
+        "boxes": boxes,
+        "extra_pixels": int((envelope & ~removal).sum()),
+        "completion_envelope": mask_statistics(envelope),
+    }
+
+
+def quality_flags_for_metrics(
+    *,
+    sharpness_ratio: float,
+    contrast_ratio: float,
+    seam_penalty: float,
+) -> list[str]:
+    """Return deterministic visual-risk flags for candidate metrics."""
+
+    flags: list[str] = []
+    if (
+        sharpness_ratio < FOG_HAZE_MAX_SHARPNESS_RATIO
+        and contrast_ratio < FOG_HAZE_MAX_CONTRAST_RATIO
+    ):
+        flags.append("fog_haze")
+    if (
+        sharpness_ratio > OVER_SHARP_MIN_SHARPNESS_RATIO
+        and seam_penalty > OVER_SHARP_MIN_SEAM_PENALTY
+    ):
+        flags.append("over_sharp_foreground_artifact")
+    return flags
+
+
+def candidate_quality(
+    image: Image.Image,
+    mask: Image.Image,
+    category: str,
+) -> dict[str, Any]:
+    """Score a visual candidate and attach conservative review-gate signals."""
+
+    rgb = np.asarray(image.convert("RGB"), dtype=np.uint8)
+    gray = cv2.cvtColor(rgb, cv2.COLOR_RGB2GRAY).astype(np.float32)
+    binary = (np.asarray(mask.convert("L")) > 127).astype(np.uint8)
+    if binary.shape != gray.shape:
+        raise ValueError(
+            f"Candidate/mask raster mismatch: image={gray.shape}, mask={binary.shape}"
+        )
+    if not binary.any():
+        raise ValueError("Candidate quality requires a nonempty visual removal mask")
+
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (17, 17))
+    outer = (cv2.dilate(binary, kernel) > 0) & ~(binary > 0)
+    inner = (binary > 0) & ~(cv2.erode(binary, kernel) > 0)
+    interior = cv2.erode(binary, np.ones((5, 5), np.uint8)) > 0
+    if not interior.any():
+        interior = binary > 0
+    if not outer.any():
+        outer = ~(binary > 0)
+    if not outer.any():
+        outer = np.ones_like(binary, dtype=bool)
+
+    gx = np.abs(cv2.Sobel(gray, cv2.CV_32F, 1, 0, ksize=3))
+    gy = np.abs(cv2.Sobel(gray, cv2.CV_32F, 0, 1, ksize=3))
+    laplacian = np.abs(cv2.Laplacian(gray, cv2.CV_32F, ksize=3))
+
+    eps = 1e-6
+    reference_sharpness = float(np.mean(laplacian[outer])) + eps
+    sharpness_ratio = float(np.mean(laplacian[interior])) / reference_sharpness
+    reference_contrast = float(np.std(gray[outer])) + eps
+    contrast_ratio = float(np.std(gray[interior])) / reference_contrast
+    seam_energy = float(np.mean((gx + gy)[inner])) if inner.any() else 0.0
+    reference_edge = float(np.mean((gx + gy)[outer])) + eps
+    seam_penalty = seam_energy / reference_edge
+
+    horizontal_fraction = float(np.mean(gy[interior])) / (
+        float(np.mean(gx[interior]) + np.mean(gy[interior])) + eps
+    )
+    structure_bonus = horizontal_fraction if category == "stairs" else 0.5
+    sharp_term = min(sharpness_ratio, 1.8) / 1.8
+    contrast_term = min(contrast_ratio, 1.5) / 1.5
+    seam_term = math.exp(-max(0.0, seam_penalty - 1.0))
+    score = (
+        0.38 * sharp_term
+        + 0.24 * contrast_term
+        + 0.23 * structure_bonus
+        + 0.15 * seam_term
+    )
+    quality_flags = quality_flags_for_metrics(
+        sharpness_ratio=sharpness_ratio,
+        contrast_ratio=contrast_ratio,
+        seam_penalty=seam_penalty,
+    )
+
+    # A flagged candidate must rank below every unflagged candidate.  Keeping
+    # the unbounded negative value preserves useful ordering when all
+    # candidates are risky and must be withheld for review.
+    gate_score = float(score) - float(len(quality_flags))
+    return {
+        "score": round(float(score), 6),
+        "gate_score": round(gate_score, 6),
+        "quality_flags": quality_flags,
+        "review_required": bool(quality_flags),
+        "sharpness_ratio": round(sharpness_ratio, 6),
+        "contrast_ratio": round(contrast_ratio, 6),
+        "horizontal_edge_fraction": round(horizontal_fraction, 6),
+        "seam_penalty": round(seam_penalty, 6),
+    }
+
+
+def candidate_clutter_metrics(
+    image: Image.Image,
+    original: Image.Image,
+    completion_envelope: np.ndarray,
+    target_amodal: np.ndarray | None,
+) -> dict[str, Any]:
+    """Measure new line/edge clutter outside the modeled support target."""
+
+    envelope = _binary_array(completion_envelope, "completion_envelope")
+    if target_amodal is None:
+        return {
+            "available": False,
+            "reason": "target_amodal_unavailable",
+        }
+    target = _binary_array(target_amodal, "target_amodal")
+    if target.shape != envelope.shape:
+        raise ValueError("Target amodal and completion envelope must have the same shape")
+
+    candidate_rgb = np.asarray(image.convert("RGB"), dtype=np.uint8)
+    original_rgb = np.asarray(original.convert("RGB"), dtype=np.uint8)
+    if candidate_rgb.shape[:2] != envelope.shape:
+        raise ValueError("Candidate and completion envelope must have the same shape")
+    if original_rgb.shape != candidate_rgb.shape:
+        raise ValueError("Original and candidate RGB rasters must have the same shape")
+
+    outside_target = envelope & ~target
+    minimum_pixels = max(256, int(round(0.001 * outside_target.size)))
+    outside_pixels = int(outside_target.sum())
+    if outside_pixels < minimum_pixels:
+        return {
+            "available": False,
+            "reason": "outside_target_clutter_unavailable",
+            "outside_target_pixels": outside_pixels,
+            "minimum_pixels": minimum_pixels,
+        }
+
+    original_gray = cv2.cvtColor(original_rgb, cv2.COLOR_RGB2GRAY)
+    candidate_gray = cv2.cvtColor(candidate_rgb, cv2.COLOR_RGB2GRAY)
+    median_gray = float(np.median(original_gray))
+    canny_low = max(20, int(0.5 * median_gray))
+    canny_high = max(canny_low + 1, min(220, int(1.2 * median_gray)))
+    edges = cv2.Canny(
+        candidate_gray,
+        canny_low,
+        canny_high,
+        L2gradient=True,
+    ) > 0
+    outside_edges = edges & outside_target
+    edge_density = float(outside_edges.sum()) / outside_pixels
+
+    height, width = outside_target.shape
+    minimum_dimension = min(height, width)
+    minimum_line_length = max(12, int(round(0.015 * minimum_dimension)))
+    maximum_line_gap = max(4, int(round(0.005 * minimum_dimension)))
+    lines = cv2.HoughLinesP(
+        outside_edges.astype(np.uint8) * 255,
+        1,
+        np.pi / 180.0,
+        threshold=minimum_line_length,
+        minLineLength=minimum_line_length,
+        maxLineGap=maximum_line_gap,
+    )
+    total_line_length = 0.0
+    line_count = 0
+    if lines is not None:
+        line_count = int(len(lines))
+        for line in lines[:, 0, :]:
+            x1, y1, x2, y2 = (int(value) for value in line)
+            total_line_length += math.hypot(x2 - x1, y2 - y1)
+    line_density_per_1000 = 1000.0 * total_line_length / outside_pixels
+    return {
+        "available": True,
+        "outside_target_pixels": outside_pixels,
+        "minimum_pixels": minimum_pixels,
+        "canny_low": canny_low,
+        "canny_high": canny_high,
+        "edge_density": round(edge_density, 8),
+        "hough_line_count": line_count,
+        "hough_minimum_line_length": minimum_line_length,
+        "hough_maximum_line_gap": maximum_line_gap,
+        "line_density_per_1000_pixels": round(line_density_per_1000, 8),
+    }
+
+
+def _average_tie_percentile_ranks(values: list[float]) -> list[float]:
+    if len(values) <= 1:
+        return [0.0] * len(values)
+    denominator = len(values) - 1
+    ranks: list[float] = []
+    for value in values:
+        lower = sum(other < value for other in values)
+        equal_other = sum(other == value for other in values) - 1
+        ranks.append((lower + 0.5 * equal_other) / denominator)
+    return ranks
+
+
+def apply_selection_clutter_penalty(
+    candidates: list[dict[str, Any]],
+    *,
+    maximum_penalty: float = 0.15,
+) -> bool:
+    """Add a cohort-relative clutter term used only to rank candidates."""
+
+    if maximum_penalty < 0:
+        raise ValueError("maximum_penalty must be non-negative")
+    if not candidates:
+        return False
+    metrics = [row["quality"].get("clutter_metrics", {}) for row in candidates]
+    if not all(metric.get("available") is True for metric in metrics):
+        for row in candidates:
+            quality = row["quality"]
+            base = float(quality.get("gate_score", quality.get("score", 0.0)))
+            quality["selection_score"] = round(base, 6)
+            quality["clutter_selection_penalty"] = None
+            quality["clutter_selection_note"] = (
+                "unavailable_fallback_to_absolute_quality_score"
+            )
+        return False
+
+    edge_ranks = _average_tie_percentile_ranks(
+        [float(metric["edge_density"]) for metric in metrics]
+    )
+    line_ranks = _average_tie_percentile_ranks(
+        [float(metric["line_density_per_1000_pixels"]) for metric in metrics]
+    )
+    for row, edge_rank, line_rank in zip(candidates, edge_ranks, line_ranks):
+        quality = row["quality"]
+        base = float(quality.get("gate_score", quality.get("score", 0.0)))
+        clutter_rank = 0.5 * (edge_rank + line_rank)
+        penalty = maximum_penalty * clutter_rank
+        quality["clutter_edge_percentile_rank"] = round(edge_rank, 6)
+        quality["clutter_line_percentile_rank"] = round(line_rank, 6)
+        quality["clutter_rank"] = round(clutter_rank, 6)
+        quality["clutter_selection_penalty"] = round(penalty, 6)
+        quality["selection_score"] = round(base - penalty, 6)
+        quality["clutter_selection_note"] = (
+            "cohort_relative_ranking_only_not_an_acceptance_or_passability_gate"
+        )
+    return True
+
+
+def select_candidate(candidates: list[dict[str, Any]]) -> tuple[dict[str, Any], str]:
+    """Select by gate score and withhold publication when every row is risky."""
+
+    if not candidates:
+        raise ValueError("At least one completion candidate is required")
+
+    def rank_key(row: dict[str, Any]) -> tuple[float, float, float, int]:
+        quality = row["quality"]
+        return (
+            float(
+                quality.get(
+                    "selection_score",
+                    quality.get("gate_score", quality.get("score", 0.0)),
+                )
+            ),
+            float(quality.get("gate_score", quality.get("score", 0.0))),
+            float(quality.get("score", 0.0)),
+            -int(row.get("index", 0)),
+        )
+
+    selected = max(candidates, key=rank_key)
+    all_risky = all(bool(row["quality"].get("quality_flags", [])) for row in candidates)
+    status = "withheld_needs_review" if all_risky else "candidate_selected_for_review"
+    return selected, status

accesspath.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""AccessPath command-line entry point for the full 2D/3D pipeline."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parent
+TOOLS = {
+    "2d": ROOT / "tools" / "accessibility_2d_completion.py",
+    "3d": ROOT / "tools" / "accessibility_3d_completion.py",
+}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        description="Run the AccessPath pipeline or one of its completion backends."
+    )
+    parser.add_argument(
+        "mode",
+        choices=("pipeline", *TOOLS),
+        help="Full Slurm pipeline, or a direct 2D/3D backend.",
+    )
+    parser.add_argument(
+        "args",
+        nargs=argparse.REMAINDER,
+        help="Arguments forwarded to the selected backend; prefix them with --.",
+    )
+    parsed = parser.parse_args()
+    forwarded = parsed.args[1:] if parsed.args[:1] == ["--"] else parsed.args
+    if parsed.mode == "pipeline":
+        from accesspath3r.cli import main as pipeline_main
+
+        sys.argv = [str(ROOT / "accesspath.py"), *forwarded]
+        return pipeline_main()
+    return subprocess.run([sys.executable, str(TOOLS[parsed.mode]), *forwarded], check=False).returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

accesspath3r/__init__.py

@@ -0,0 +1,3 @@
+"""Accessibility3R: accessibility-scene 2D and 3D amodal completion."""
+
+__version__ = "0.2.0"

accesspath3r/cli.py

@@ -0,0 +1,809 @@
+#!/usr/bin/env python3
+"""AccessibilityAmodal one-command mask, 2D completion, and 3D inference.
+
+This is a lightweight login-node launcher.  GPU work is submitted to Slurm via
+``slurm/run_accesspath_demo.sbatch``; this process can wait for the
+job and report the persistent result directory.
+
+The third-party Accessibility3D model is accessed only through the project adapter
+``tools/accessibility_3d_completion.py``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+
+from accesspath3r.privacy import public_path, sanitize_text
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+SBATCH_SCRIPT = PROJECT_ROOT / "slurm" / "run_accesspath_demo.sbatch"
+PRIMARY_3D_DIRNAME = "accessibility3d"
+DEFAULT_PROMPT_CONFIG = (
+    PROJECT_ROOT / "configs" / "accessibility_mask_prompts_e5_v2.json"
+)
+STRUCTURAL_STAIRS_PROMPT_CONFIG = (
+    PROJECT_ROOT / "configs" / "accessibility_stairs_structural_occlusion_prompts.json"
+)
+OUTDOOR_STAIRS_NO_OCCLUSION_PROMPT_CONFIG = (
+    PROJECT_ROOT / "configs" / "accessibility_stairs_outdoor_no_occlusion_prompts.json"
+)
+CATEGORIES = ("curb_cut", "ramp", "stairs", "tactile_paving", "walkway")
+GEOMETRY_ALLOWED_2D_STATUSES = {
+    "candidate_selected_for_review",
+    "skipped_empty_removal_mask",
+}
+TERMINAL_STATES = {
+    "BOOT_FAIL",
+    "CANCELLED",
+    "COMPLETED",
+    "DEADLINE",
+    "FAILED",
+    "NODE_FAIL",
+    "OUT_OF_MEMORY",
+    "PREEMPTED",
+    "REVOKED",
+    "TIMEOUT",
+}
+
+
+def safe_sample_id(value: str) -> str:
+    result = re.sub(r"[^A-Za-z0-9_-]+", "_", value).strip("_")
+    return result or "single_image"
+
+
+def normalized_state(value: str) -> str:
+    return value.strip().split()[0].split("+")[0] if value.strip() else ""
+
+
+def run_command(command: list[str]) -> subprocess.CompletedProcess[str]:
+    return subprocess.run(
+        command,
+        cwd=PROJECT_ROOT,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+
+
+def query_job_state(job_id: str) -> str | None:
+    queued = run_command(["squeue", "-h", "-j", job_id, "-o", "%T"])
+    if queued.returncode == 0 and queued.stdout.strip():
+        return normalized_state(queued.stdout.splitlines()[0])
+
+    accounting = run_command(
+        [
+            "sacct",
+            "-n",
+            "-P",
+            "-j",
+            job_id,
+            "--format=JobIDRaw,State,ExitCode",
+        ]
+    )
+    if accounting.returncode != 0:
+        return None
+    for line in accounting.stdout.splitlines():
+        fields = line.split("|")
+        if len(fields) >= 2 and fields[0] == job_id:
+            return normalized_state(fields[1])
+    return None
+
+
+def format_clock(seconds: float) -> str:
+    seconds = max(0, int(round(seconds)))
+    hours, remainder = divmod(seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    if hours:
+        return f"{hours:d}:{minutes:02d}:{seconds:02d}"
+    return f"{minutes:02d}:{seconds:02d}"
+
+
+def parse_timestamp(value: object) -> float | None:
+    if not isinstance(value, str):
+        return None
+    try:
+        return datetime.fromisoformat(value).timestamp()
+    except ValueError:
+        return None
+
+
+def read_progress(output_dir: Path) -> dict | None:
+    try:
+        value = json.loads((output_dir / "progress.json").read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return None
+    return value if isinstance(value, dict) else None
+
+
+def infer_progress_from_artifacts(
+    output_dir: Path,
+    sample_id: str,
+    include_generative_3d: bool,
+) -> dict | None:
+    """Provide useful progress for jobs launched before progress.json existed."""
+    presentation_manifest = (
+        output_dir
+        / "04_3d_completion"
+        / "geometry"
+        / "presentation_models"
+        / "manifest.json"
+    )
+    legacy_variants_manifest = (
+        output_dir
+        / "04_3d_completion"
+        / "geometry"
+        / "3d_variants"
+        / "manifest.json"
+    )
+    if not presentation_manifest.is_file() and legacy_variants_manifest.is_file():
+        presentation_manifest = legacy_variants_manifest
+    learned_manifest = output_dir / PRIMARY_3D_DIRNAME / "manifest.json"
+    current_compatibility_manifest = (
+        output_dir / "04_3d_completion" / "visual_candidate" / "manifest.json"
+    )
+    if not learned_manifest.is_file() and current_compatibility_manifest.is_file():
+        learned_manifest = current_compatibility_manifest
+    final_marker = learned_manifest if include_generative_3d else presentation_manifest
+    if final_marker.is_file():
+        return {
+            "status": "completed",
+            "percent": 100.0,
+            "stage_label": "All outputs completed",
+        }
+    milestones = (
+        (
+            learned_manifest,
+            96.0,
+            "Accessibility3D CUDA Gaussian rotation and dense triangle mesh",
+        ),
+        (
+            presentation_manifest,
+            74.0,
+            "Diagnostic category-constrained geometry",
+        ),
+        (
+            output_dir / "04_3d_completion" / "geometry" / "completed_mesh_turntable_slow.gif",
+            44.0,
+            "Continuous-surface and solid 3D views",
+        ),
+        (
+            output_dir / "04_3d_completion" / "geometry" / "geometry_manifest.json",
+            43.0,
+            "Basic 3D turntable preview",
+        ),
+        (
+            output_dir / "03_2d_completion" / "completed_rgb_selected.png",
+            34.0,
+            "Depth and 3D geometry reconstruction",
+        ),
+        (
+            output_dir / "02_masks" / "metadata.json",
+            20.0,
+            "GPU generative 2D completion and candidate selection",
+        ),
+        (
+            output_dir / "01_sam3" / "summary.json",
+            16.0,
+            "Visible, hidden, amodal, and obstacle masks",
+        ),
+    )
+    for marker, percent, label in milestones:
+        if marker.is_file():
+            return {"status": "running", "percent": percent, "stage_label": label}
+    return None
+
+
+def interpolated_percent(progress: dict, now: float) -> float:
+    try:
+        percent = float(progress.get("percent", 0.0))
+    except (TypeError, ValueError):
+        percent = 0.0
+    if progress.get("status") != "running":
+        return max(0.0, min(100.0, percent))
+    try:
+        end_percent = float(progress.get("stage_end_percent", percent))
+        expected = float(progress.get("stage_expected_seconds", 0.0))
+    except (TypeError, ValueError):
+        return max(0.0, min(99.0, percent))
+    stage_started = parse_timestamp(progress.get("stage_started_at"))
+    if stage_started is None or expected <= 0 or end_percent <= percent:
+        return max(0.0, min(99.0, percent))
+    fraction = max(0.0, min(0.98, (now - stage_started) / expected))
+    interpolated = percent + (end_percent - percent) * fraction
+    return max(0.0, min(99.0, interpolated))
+
+
+def estimated_remaining_seconds(
+    progress: dict | None,
+    now: float,
+    elapsed: float,
+    base_total: float,
+) -> float:
+    """Keep ETA conservative when a stage or an earlier stage runs long."""
+    adjusted_total = max(1.0, base_total)
+    if not progress or progress.get("status") != "running":
+        return max(0.0, adjusted_total - elapsed)
+    overall_started = parse_timestamp(progress.get("started_at"))
+    stage_started = parse_timestamp(progress.get("stage_started_at"))
+    try:
+        start_percent = float(progress.get("percent", 0.0))
+        stage_expected = float(progress.get("stage_expected_seconds", 0.0))
+    except (TypeError, ValueError):
+        return max(0.0, adjusted_total - elapsed)
+    if overall_started is not None and stage_started is not None:
+        planned_stage_start = max(0.0, start_percent) / 100.0 * base_total
+        actual_stage_start = max(0.0, stage_started - overall_started)
+        adjusted_total += max(0.0, actual_stage_start - planned_stage_start)
+        adjusted_total += max(0.0, now - stage_started - stage_expected)
+    return max(0.0, adjusted_total - elapsed)
+
+
+class ProgressDisplay:
+    def __init__(self, job_id: str) -> None:
+        self.job_id = job_id
+        self.is_tty = sys.stdout.isatty()
+        self.last_key: tuple[str, str] | None = None
+        self.last_width = 0
+
+    def update(
+        self,
+        percent: float,
+        label: str,
+        elapsed: float,
+        eta: float | None,
+        state: str,
+        final: bool = False,
+    ) -> None:
+        width = 28
+        filled = min(width, max(0, int(round(width * percent / 100.0))))
+        bar = "#" * filled + "-" * (width - filled)
+        if state == "PENDING":
+            timing = f"queue {format_clock(elapsed)} | GPU ETA ~{format_clock(eta or 0)}"
+        elif state == "FAILED":
+            timing = f"elapsed {format_clock(elapsed)} | failed"
+        elif eta is None:
+            timing = f"elapsed {format_clock(elapsed)} | ETA calculating"
+        elif eta <= 0 and not final:
+            timing = f"elapsed {format_clock(elapsed)} | finishing"
+        else:
+            timing = f"elapsed {format_clock(elapsed)} | ETA ~{format_clock(eta)}"
+        line = (
+            f"[Slurm {self.job_id}] [{bar}] {percent:5.1f}% | "
+            f"{label} | {timing}"
+        )
+        key = (state, label)
+        if self.is_tty:
+            padding = " " * max(0, self.last_width - len(line))
+            print(f"\r{line}{padding}", end="\n" if final else "", flush=True)
+            self.last_width = len(line)
+        elif key != self.last_key or final:
+            print(line, flush=True)
+        self.last_key = key
+
+
+def wait_for_job(
+    job_id: str,
+    poll_seconds: float,
+    output_dir: Path,
+    sample_id: str,
+    include_generative_3d: bool,
+    estimated_seconds: float,
+) -> str:
+    missing_polls = 0
+    submitted_at = time.monotonic()
+    running_at: float | None = None
+    display = ProgressDisplay(job_id)
+    while True:
+        state = query_job_state(job_id)
+        now_wall = time.time()
+        now_monotonic = time.monotonic()
+        progress = read_progress(output_dir) or infer_progress_from_artifacts(
+            output_dir,
+            sample_id,
+            include_generative_3d,
+        )
+
+        if state:
+            missing_polls = 0
+            if state == "RUNNING" and running_at is None:
+                running_at = now_monotonic
+        else:
+            # sacct can lag briefly after a job leaves squeue.
+            missing_polls += 1
+            if missing_polls >= 12 and not progress:
+                raise RuntimeError(
+                    "Unable to read the job state from squeue or sacct. "
+                    f"Check manually with: squeue -j {job_id}"
+                )
+
+        progress_status = progress.get("status") if progress else None
+        if progress_status == "completed":
+            runtime_started = parse_timestamp(progress.get("started_at"))
+            elapsed = now_wall - runtime_started if runtime_started else 0.0
+            display.update(100.0, "All outputs completed", elapsed, 0.0, "COMPLETED", final=True)
+            return "COMPLETED"
+        if progress_status == "failed":
+            runtime_started = parse_timestamp(progress.get("started_at"))
+            elapsed = now_wall - runtime_started if runtime_started else 0.0
+            display.update(
+                interpolated_percent(progress, now_wall),
+                str(progress.get("message") or progress.get("stage_label") or "GPU stage failed"),
+                elapsed,
+                None,
+                "FAILED",
+                final=True,
+            )
+            return "FAILED"
+
+        if state == "PENDING":
+            display.update(
+                0.0,
+                "Waiting for a GPU",
+                now_monotonic - submitted_at,
+                estimated_seconds,
+                state,
+            )
+        else:
+            if running_at is None:
+                running_at = now_monotonic
+            runtime_started = parse_timestamp(progress.get("started_at")) if progress else None
+            elapsed = (
+                max(0.0, now_wall - runtime_started)
+                if runtime_started is not None
+                else now_monotonic - running_at
+            )
+            total_estimate = estimated_seconds
+            if progress:
+                try:
+                    total_estimate = float(progress.get("total_estimated_seconds", estimated_seconds))
+                except (TypeError, ValueError):
+                    pass
+            percent = interpolated_percent(progress, now_wall) if progress else 0.0
+            label = (
+                str(progress.get("stage_label") or "Initializing GPU job")
+                if progress
+                else "Initializing GPU job"
+            )
+            display.update(
+                percent,
+                label,
+                elapsed,
+                estimated_remaining_seconds(progress, now_wall, elapsed, total_estimate),
+                state or "UNKNOWN",
+                final=bool(state in TERMINAL_STATES),
+            )
+
+        if state in TERMINAL_STATES:
+            return state
+        time.sleep(poll_seconds)
+
+
+def estimate_runtime_seconds(args: argparse.Namespace) -> int:
+    # Broad SAM3 prompt evaluation and the presentation-model renderer scale
+    # with image size.  These values are calibrated from the 1368x1824 9528
+    # run; GLB texture baking is accounted for separately because it dominated
+    # that job's final stage instead of behaving like the normal mesh export.
+    seconds = (5 if args.reviewed_visible_workspace else 150) + 13 + (24 if not args.no_depth else 6) + 3 + 420
+    if not args.no_2d:
+        seconds += 40
+    if args.fast_2d_baseline:
+        seconds += 12
+    if not args.no_generative_3d:
+        seconds += 75
+        if args.export_glb:
+            seconds += 540
+    return seconds
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Submit one accessibility image to SAM3 mask inference, amodal/hidden "
+            "completion, 2D completion, Depth Anything geometry reconstruction, "
+            "and Accessibility3D CUDA Gaussian rendering with a dense triangle mesh."
+        )
+    )
+    parser.add_argument("image_pos", nargs="?", help="Input RGB image (positional form).")
+    parser.add_argument("--image", dest="image_opt", help="Input RGB image.")
+    parser.add_argument("--category", required=True, choices=CATEGORIES)
+    parser.add_argument("--sample-id", default=None)
+    parser.add_argument(
+        "--output-dir",
+        default=None,
+        help=(
+            "Persistent output directory. "
+            "Default: output/inference/<sample>_<time>."
+        ),
+    )
+    parser.add_argument(
+        "--prompt-config",
+        default=None,
+        help=(
+            "Optional expert override for the mask prompt JSON. By default, a unified "
+            "target/occluder prompt bank is evaluated against the input image, so the "
+            "caller does not need to choose a scene-specific JSON."
+        ),
+    )
+    parser.add_argument(
+        "--reviewed-visible-workspace",
+        default=None,
+        help=(
+            "A one-image workspace saved by serve_accessibility_visible_mask_review.py. "
+            "Requires explicit human approval; replaces the SAM3 visible-target proposal only."
+        ),
+    )
+    parser.add_argument(
+        "--structural-occluder",
+        action="store_true",
+        help=(
+            "For stairs occluded by a pillar, newel post, banister, or railing. "
+            "Selects the dedicated structural-occlusion prompt config."
+        ),
+    )
+    parser.add_argument(
+        "--no-target-occluder",
+        action="store_true",
+        help=(
+            "For a visible outdoor stair flight with no target-surface occluder. "
+            "Uses prompts that exclude permanent handrails and side walls from the obstacle mask."
+        ),
+    )
+    parser.add_argument(
+        "--sd-2d",
+        action="store_true",
+        help="Legacy compatibility flag; GPU generative 2D completion is enabled by default.",
+    )
+    parser.add_argument(
+        "--fast-2d-baseline",
+        action="store_true",
+        help="Also produce the old OpenCV 2D baseline for comparison (not a primary result).",
+    )
+    parser.add_argument("--no-2d", action="store_true", help="Skip GPU generative 2D completion.")
+    parser.add_argument("--no-depth", action="store_true", help="Use debug perspective geometry instead of Depth Anything.")
+    parser.add_argument(
+        "--no-generative-3d",
+        action="store_true",
+        help="Skip the primary Accessibility3D CUDA rotation and dense learned mesh.",
+    )
+    parser.add_argument(
+        "--export-glb",
+        action="store_true",
+        help="Also export the Accessibility3D dense triangle result as mesh.glb.",
+    )
+    parser.add_argument("--allow-large-2d", action="store_true", help="Allow 2D completion masks larger than the normal safety gate.")
+    parser.add_argument("--no-wait", action="store_true", help="Submit and return immediately instead of waiting for results.")
+    parser.add_argument("--poll-seconds", type=float, default=5.0, help=argparse.SUPPRESS)
+    parser.add_argument("--dry-run", action="store_true", help="Validate and print the planned submission without submitting.")
+    return parser
+
+
+def resolve_args(args: argparse.Namespace, parser: argparse.ArgumentParser) -> dict[str, str]:
+    if bool(args.image_pos) == bool(args.image_opt):
+        parser.error("provide exactly one image, either positional or with --image")
+    image = Path(args.image_opt or args.image_pos).expanduser().resolve()
+    if not image.is_file():
+        parser.error(
+            "input image does not exist: "
+            f"{public_path(image, project_root=PROJECT_ROOT)}"
+        )
+    if args.poll_seconds < 2:
+        parser.error("--poll-seconds must be at least 2")
+    if args.structural_occluder and args.category != "stairs":
+        parser.error("--structural-occluder currently applies only to --category stairs")
+    if args.no_target_occluder and args.category != "stairs":
+        parser.error("--no-target-occluder currently applies only to --category stairs")
+    if args.structural_occluder and args.no_target_occluder:
+        parser.error("--structural-occluder and --no-target-occluder are mutually exclusive")
+    if (args.structural_occluder or args.no_target_occluder) and args.prompt_config:
+        parser.error("choose one of --structural-occluder, --no-target-occluder, or --prompt-config")
+    reviewed_visible_workspace = None
+    if args.reviewed_visible_workspace:
+        reviewed_visible_workspace = Path(args.reviewed_visible_workspace).expanduser().resolve()
+        if not reviewed_visible_workspace.is_dir():
+            parser.error(
+                "reviewed-visible workspace does not exist: "
+                f"{public_path(reviewed_visible_workspace, project_root=PROJECT_ROOT)}"
+            )
+
+    if args.structural_occluder:
+        prompt_config = STRUCTURAL_STAIRS_PROMPT_CONFIG
+    elif args.no_target_occluder:
+        prompt_config = OUTDOOR_STAIRS_NO_OCCLUSION_PROMPT_CONFIG
+    elif args.prompt_config:
+        prompt_config = Path(args.prompt_config).expanduser().resolve()
+    else:
+        prompt_config = DEFAULT_PROMPT_CONFIG
+    if not prompt_config.is_file():
+        parser.error(
+            "prompt config does not exist: "
+            f"{public_path(prompt_config, project_root=PROJECT_ROOT)}"
+        )
+    if not SBATCH_SCRIPT.is_file():
+        parser.error(
+            "Slurm script does not exist: "
+            f"{public_path(SBATCH_SCRIPT, project_root=PROJECT_ROOT)}"
+        )
+    if shutil.which("sbatch") is None:
+        parser.error("sbatch is unavailable; run this command on the configured Slurm server")
+
+    sample_id = safe_sample_id(args.sample_id or image.stem)
+    if args.output_dir:
+        output_dir = Path(args.output_dir).expanduser().resolve()
+    else:
+        timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+        output_dir = PROJECT_ROOT / "output" / "inference" / f"{sample_id}_{timestamp}"
+
+    return {
+        "IMAGE": str(image),
+        "CATEGORY": args.category,
+        "SAMPLE_ID": sample_id,
+        "OUTPUT_DIR": str(output_dir),
+        "PROMPT_CONFIG": str(prompt_config),
+        "RUN_GPU_2D": "0" if args.no_2d else "1",
+        "RUN_FAST_2D": "1" if args.fast_2d_baseline else "0",
+        "ALLOW_LARGE_2D": "1" if args.allow_large_2d else "0",
+        "RUN_DEPTH": "0" if args.no_depth else "1",
+        "RUN_ACCESSIBILITYAMODAL_VISUAL_3D": "0" if args.no_generative_3d else "1",
+        "EXPORT_ACCESSIBILITYAMODAL_VISUAL_GLB": "1" if args.export_glb else "0",
+        "NO_TARGET_OCCLUDER": "1" if args.no_target_occluder else "0",
+        "REVIEWED_VISIBLE_WORKSPACE": str(reviewed_visible_workspace) if reviewed_visible_workspace else "",
+    }
+
+
+def print_result_paths(
+    output_dir: Path,
+    sample_id: str,
+    include_gpu_2d: bool,
+    include_generative_3d: bool,
+    include_glb: bool,
+    reviewed_visible: bool = False,
+) -> None:
+    def shown(path: Path) -> str:
+        return public_path(
+            path,
+            project_root=PROJECT_ROOT,
+            output_root=output_dir,
+        )
+
+    print("\nResults:")
+    print(f"  output root:       {shown(output_dir)}")
+    if include_gpu_2d:
+        print(
+            f"  quick review:      "
+            f"{shown(output_dir / '00_quick_review' / 'overview.jpg')}"
+        )
+    if reviewed_visible:
+        print(f"  reviewed visible:  {shown(output_dir / '01_reviewed_visible' / 'metadata.json')}")
+    else:
+        print(f"  SAM3 overlay:      {shown(output_dir / '01_sam3' / 'samples' / sample_id / 'overlay.png')}")
+    print(f"  mask overlay:      {shown(output_dir / '02_masks' / 'mask_overlay.png')}")
+    print(f"  visible mask:      {shown(output_dir / '02_masks' / 'target_visible.png')}")
+    print(f"  hidden mask:       {shown(output_dir / '02_masks' / 'hidden.png')}")
+    print(f"  amodal mask:       {shown(output_dir / '02_masks' / 'target_amodal.png')}")
+    print(f"  obstacle mask:     {shown(output_dir / '02_masks' / 'obstacle.png')}")
+    if include_gpu_2d:
+        print(f"  GPU 2D selected:   {shown(output_dir / '03_2d_completion' / 'completed_rgb_selected.png')}")
+        print(f"  GPU 2D candidates: {shown(output_dir / '03_2d_completion' / 'candidate_comparison.jpg')}")
+    print(f"  depth diagnostic:  {shown(output_dir / '04_3d_completion' / 'geometry' / 'completed_depth_vis.png')}")
+    print(f"  point-cloud debug: {shown(output_dir / '04_3d_completion' / 'geometry' / 'completed_point_cloud.ply')}")
+    print(f"  geometry debug:    {shown(output_dir / '04_3d_completion' / 'geometry' / 'completed_mesh.ply')}")
+    print(f"  geometry fallback: {shown(output_dir / '04_3d_completion' / 'turntable' / 'turntable.gif')}")
+    print(
+        "  presentation 3D:   "
+        f"{shown(output_dir / '04_3d_completion' / 'geometry' / 'presentation_models')}"
+    )
+    if include_generative_3d:
+        visual_dir = output_dir / PRIMARY_3D_DIRNAME
+        print(f"  quality checks:   {shown(output_dir / '05_quality_checks' / 'verification.json')}")
+        print(f"  primary 3D GIF:   {shown(visual_dir / 'sample_gaussian.gif')}")
+        print(f"  mesh normal diag: {shown(visual_dir / 'sample_mesh.gif')}")
+        print(f"  primary 3D views: {shown(visual_dir / 'multiview_contact_sheet.jpg')}")
+        print(f"  dense face mesh:  {shown(visual_dir / 'mesh.ply')}")
+        if include_glb:
+            print(f"  textured 3D GLB:  {shown(visual_dir / 'mesh.glb')}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    job_env = resolve_args(args, parser)
+    output_dir = Path(job_env["OUTPUT_DIR"])
+    sample_id = job_env["SAMPLE_ID"]
+
+    print("AccessibilityAmodal one-command inference")
+    print(
+        "  image:         "
+        f"{public_path(job_env['IMAGE'], project_root=PROJECT_ROOT)}"
+    )
+    print(f"  category:      {job_env['CATEGORY']}")
+    if job_env["REVIEWED_VISIBLE_WORKSPACE"]:
+        print("  visible mask:   human-reviewed workspace (SAM3 proposal bypassed)")
+        print("  prompt config:  not used after reviewed-mask validation")
+    else:
+        print(
+            "  prompt config: "
+            f"{public_path(job_env['PROMPT_CONFIG'], project_root=PROJECT_ROOT)}"
+        )
+    print(
+        "  output:        "
+        f"{public_path(output_dir, project_root=PROJECT_ROOT, output_root=output_dir)}"
+    )
+    print("  GPU execution: Slurm, one GPU (5090 partition)")
+    print(
+        "  3D outputs:    diagnostic depth/point cloud"
+        + (
+            " + primary Accessibility3D CUDA Gaussian rotation/dense mesh"
+            if not args.no_generative_3d
+            else " + category-geometry fallback"
+        )
+    )
+    estimated_seconds = estimate_runtime_seconds(args)
+    print(
+        f"  estimated time: about {format_clock(estimated_seconds)} after GPU starts "
+        "(Slurm queue excluded)"
+    )
+
+    command = ["sbatch", "--parsable", "--export=ALL", str(SBATCH_SCRIPT)]
+    if args.dry_run:
+        print("Dry run; no job submitted.")
+        shown_command = [*command[:-1], public_path(command[-1], project_root=PROJECT_ROOT)]
+        print("  " + " ".join(shown_command))
+        return 0
+
+    environment = os.environ.copy()
+    environment.update(job_env)
+    submitted = subprocess.run(
+        command,
+        cwd=PROJECT_ROOT,
+        env=environment,
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if submitted.returncode != 0:
+        detail = submitted.stderr.strip() or submitted.stdout.strip()
+        raise RuntimeError(
+            "Slurm submission failed: "
+            + sanitize_text(
+                detail,
+                project_root=PROJECT_ROOT,
+                output_root=output_dir,
+                sensitive_paths=(job_env["IMAGE"], job_env["PROMPT_CONFIG"]),
+            )
+        )
+    job_id = submitted.stdout.strip().split(";")[0]
+    if not job_id.isdigit():
+        raise RuntimeError(f"Could not parse Slurm job ID from: {submitted.stdout!r}")
+
+    print(f"Submitted Slurm job {job_id}")
+    print(f"  stdout: Logs/slurm-{job_id}.out")
+    print(f"  stderr: Logs/slurm-{job_id}.err")
+    if args.no_wait:
+        print(f"Monitor with: squeue -j {job_id}")
+        print_result_paths(
+            output_dir,
+            sample_id,
+            not args.no_2d,
+            not args.no_generative_3d,
+            args.export_glb,
+            bool(job_env["REVIEWED_VISIBLE_WORKSPACE"]),
+        )
+        return 0
+
+    try:
+        state = wait_for_job(
+            job_id,
+            args.poll_seconds,
+            output_dir,
+            sample_id,
+            not args.no_generative_3d,
+            estimated_seconds,
+        )
+    except KeyboardInterrupt:
+        print(
+            f"\nStopped waiting; Slurm job {job_id} is still managed separately. "
+            f"Cancel it only if needed with: scancel {job_id}",
+            file=sys.stderr,
+        )
+        return 130
+
+    if state != "COMPLETED":
+        raise RuntimeError(
+            f"Slurm job {job_id} ended with state {state}. "
+            f"Inspect Logs/slurm-{job_id}.err"
+        )
+    expected = output_dir / "02_masks" / "mask_overlay.png"
+    if not expected.is_file():
+        raise RuntimeError(
+            f"Slurm job {job_id} completed but the expected mask output is missing: "
+            f"{public_path(expected, project_root=PROJECT_ROOT, output_root=output_dir)}"
+        )
+    preflight_path = output_dir / "05_quality_checks" / "preflight.json"
+    if preflight_path.is_file():
+        try:
+            preflight = json.loads(preflight_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            preflight = {}
+        if preflight.get("decision") != "accept":
+            print(
+                "\n3D generation was intentionally withheld because the mask/structure "
+                "preflight requires re-prompting or human review."
+            )
+            print(
+                "  verification: "
+                f"{public_path(preflight_path, project_root=PROJECT_ROOT, output_root=output_dir)}"
+            )
+            print("Automatic masks are review candidates, not ground truth.")
+            return 0
+    completion_manifest_path = output_dir / "03_2d_completion" / "manifest.json"
+    if not args.no_2d:
+        if not completion_manifest_path.is_file():
+            raise RuntimeError(
+                "Slurm job completed but the 2D completion manifest is missing: "
+                f"{public_path(completion_manifest_path, project_root=PROJECT_ROOT, output_root=output_dir)}"
+            )
+        try:
+            completion_manifest = json.loads(
+                completion_manifest_path.read_text(encoding="utf-8")
+            )
+        except (json.JSONDecodeError, OSError) as exc:
+            raise RuntimeError("The 2D completion manifest is unreadable") from exc
+        completion_status = completion_manifest.get("status")
+        if completion_status not in GEOMETRY_ALLOWED_2D_STATUSES:
+            print(
+                "\nThe 2D result needs review and was not used to condition 3D: "
+                f"{completion_status!r}. Accessibility3D used the original RGB and strict "
+                "three-value mask instead."
+            )
+            comparison = output_dir / "03_2d_completion" / "candidate_comparison.jpg"
+            if comparison.is_file():
+                print(
+                    "  candidates: "
+                    f"{public_path(comparison, project_root=PROJECT_ROOT, output_root=output_dir)}"
+                )
+
+    if not args.no_generative_3d:
+        verification_path = output_dir / "05_quality_checks" / "verification.json"
+        if not verification_path.is_file():
+            raise RuntimeError(
+                "Slurm job completed but the generated-3D verification report is missing: "
+                f"{public_path(verification_path, project_root=PROJECT_ROOT, output_root=output_dir)}"
+            )
+        try:
+            verification = json.loads(verification_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError) as exc:
+            raise RuntimeError("Generated-3D verification report is unreadable") from exc
+        if verification.get("decision") != "accept":
+            print(
+                "\nThe Accessibility3D result remains available for human review, but its "
+                "structured verification did not accept automatic use."
+            )
+            print(
+                "  verification: "
+                f"{public_path(verification_path, project_root=PROJECT_ROOT, output_root=output_dir)}"
+            )
+
+    print_result_paths(
+        output_dir,
+        sample_id,
+        not args.no_2d,
+        not args.no_generative_3d,
+        args.export_glb,
+        bool(job_env["REVIEWED_VISIBLE_WORKSPACE"]),
+    )
+    print("\nAutomatic masks are review candidates, not ground truth.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

accesspath3r/privacy.py

@@ -0,0 +1,145 @@
+"""Privacy-safe formatting for console output, logs, and public artifacts."""
+
+from __future__ import annotations
+
+import os
+import re
+import socket
+from pathlib import Path
+from typing import Iterable
+
+
+EMAIL_PATTERN = re.compile(
+    r"(?<![A-Za-z0-9._%+-])[A-Za-z0-9._%+-]+@"
+    r"[A-Za-z0-9.-]+\.[A-Za-z]{2,}(?![A-Za-z0-9.-])"
+)
+HOME_PATH_PATTERN = re.compile(r"/(?:home|Users)/[^/\s:'\"]+")
+DATA_USER_PATH_PATTERN = re.compile(r"/data\d*/userdata/[^/\s:'\"]+")
+SECRET_QUERY_PATTERN = re.compile(
+    r"(?i)(\b(?:access[_-]?token|api[_-]?key|password|secret|token)=)"
+    r"[^&\s]+"
+)
+IPV4_PATTERN = re.compile(r"(?<![\d.])(?:\d{1,3}\.){3}\d{1,3}(?![\d.])")
+
+
+def _resolved(path: str | os.PathLike[str] | Path) -> Path:
+    return Path(path).expanduser().resolve(strict=False)
+
+
+def public_path(
+    path: str | os.PathLike[str] | Path,
+    *,
+    project_root: str | os.PathLike[str] | Path,
+    output_root: str | os.PathLike[str] | Path | None = None,
+) -> str:
+    """Return a useful path label without exposing a workstation/user prefix."""
+    resolved = _resolved(path)
+    project = _resolved(project_root)
+    try:
+        relative = resolved.relative_to(project)
+        return relative.as_posix() or "."
+    except ValueError:
+        pass
+
+    if output_root is not None:
+        output = _resolved(output_root)
+        try:
+            relative = resolved.relative_to(output)
+            suffix = relative.as_posix()
+            return "${OUTPUT_DIR}" + (f"/{suffix}" if suffix else "")
+        except ValueError:
+            pass
+
+    home_value = os.environ.get("HOME")
+    if home_value:
+        home = _resolved(home_value)
+        try:
+            relative = resolved.relative_to(home)
+            suffix = relative.as_posix()
+            return "~" + (f"/{suffix}" if suffix else "")
+        except ValueError:
+            pass
+
+    return f"<external>/{resolved.name}" if resolved.name else "<external>"
+
+
+def _replacement_pairs(
+    *,
+    project_root: str | os.PathLike[str] | Path | None,
+    output_root: str | os.PathLike[str] | Path | None,
+    sensitive_paths: Iterable[str | os.PathLike[str] | Path],
+) -> list[tuple[str, str]]:
+    pairs: list[tuple[str, str]] = []
+
+    def add(value: str | os.PathLike[str] | Path | None, label: str) -> None:
+        if value is None or not str(value).strip():
+            return
+        raw = str(value).rstrip("/")
+        # Relative values such as "." are meaningful CLI inputs but unsafe
+        # replacement needles ("." would rewrite every decimal and suffix).
+        if raw and Path(raw).expanduser().is_absolute():
+            pairs.append((raw, label))
+        try:
+            resolved = str(_resolved(value)).rstrip("/")
+        except (OSError, RuntimeError, ValueError):
+            return
+        if resolved and resolved not in {".", "/"} and resolved != raw:
+            pairs.append((resolved, label))
+
+    add(output_root, "${OUTPUT_DIR}")
+    add(project_root, "${PROJECT_ROOT}")
+    add(os.environ.get("HOME"), "${HOME}")
+
+    for index, path in enumerate(sensitive_paths, start=1):
+        add(path, f"${{PRIVATE_PATH_{index}}}")
+
+    # Replace longer prefixes first so OUTPUT_DIR wins over PROJECT_ROOT.
+    return sorted(set(pairs), key=lambda pair: len(pair[0]), reverse=True)
+
+
+def sanitize_text(
+    text: str,
+    *,
+    project_root: str | os.PathLike[str] | Path | None = None,
+    output_root: str | os.PathLike[str] | Path | None = None,
+    sensitive_paths: Iterable[str | os.PathLike[str] | Path] = (),
+) -> str:
+    """Redact local identity/path details while retaining diagnostic meaning."""
+    result = text
+    for value, label in _replacement_pairs(
+        project_root=project_root,
+        output_root=output_root,
+        sensitive_paths=sensitive_paths,
+    ):
+        result = result.replace(value, label)
+
+    result = HOME_PATH_PATTERN.sub("${HOME}", result)
+    result = DATA_USER_PATH_PATTERN.sub("${HOME}", result)
+    result = EMAIL_PATTERN.sub("<redacted-email>", result)
+    result = SECRET_QUERY_PATTERN.sub(r"\1<redacted>", result)
+
+    def redact_ipv4(match: re.Match[str]) -> str:
+        value = match.group(0)
+        octets = value.split(".")
+        if any(int(octet) > 255 for octet in octets) or value.startswith("127."):
+            return value
+        return "<redacted-ip>"
+
+    result = IPV4_PATTERN.sub(redact_ipv4, result)
+
+    identity_values = {
+        os.environ.get("USER", ""),
+        os.environ.get("LOGNAME", ""),
+        os.environ.get("HOSTNAME", ""),
+        socket.gethostname(),
+    }
+    for value in sorted(identity_values, key=len, reverse=True):
+        # Avoid replacing common words such as "root" in ordinary diagnostics.
+        if len(value) < 4 or value.lower() in {"root", "user", "admin"}:
+            continue
+        result = re.sub(
+            rf"(?<![A-Za-z0-9_.-]){re.escape(value)}(?![A-Za-z0-9_.-])",
+            "<redacted-identity>",
+            result,
+        )
+    return result

checksums.sha256

@@ -0,0 +1,39 @@
+1e8416b2bf9a40f8acbadd4b8022991ae2a4e31e2788eccbcd14a1b239f45f65  ./accessibilityamodal/category_overrides.py
+f4d13e3551e673d463533afe15c261c737ae2f2306b2bf8ce5ae3b33d2d27060  ./accessibilityamodal/depth.py
+a104312a59a92c36b64c4e1d0496888a53556f7196098209fc8995eec3b763e9  ./accessibilityamodal/geometry_analysis.py
+ffd43f475c991eadf62c21930bc152ea4ae5224cbecededecd97b09e728ed8b3  ./accessibilityamodal/__init__.py
+a088e86abdd7979ba7fc446d0ca14b44291277a1319368057916e095861207dd  ./accessibilityamodal/pipeline.py
+8e86aea92c34a8594d21f30a4d76f550e99beadedeb83f55772bc8402d487c03  ./accessibilityamodal/reconstruct.py
+aecc62c1549d5743f1d581c07b647e88f66c1a42f86e85c2e0a98d992eb65880  ./accessibilityamodal/sam_refinement.py
+7fb2b6fee108870792824b1e07677de38fdfcdf1a4e0032d58807750e4315100  ./accessibilityamodal/verification.py
+69eade48cdd5137949c872e7af0ed3f62566ec4e1a51fdff3cd76b695381340b  ./accessibilityamodal/visual_completion.py
+0f8001502b13d74a4741dc4ba90c5eed5deb11c169cbb4b16c6f4ac2ddef874c  ./accesspath3r/cli.py
+3bb666ae061f470306b4641b7433d6a576907d0c1f56984f6dae6b4734cebd1b  ./accesspath3r/__init__.py
+cecfb61d0694188d371c36843a18e8cc597c41ff3e301abc617fd917ddba502c  ./accesspath3r/privacy.py
+c88c5f5745fd7bd5a2f0e820c6601fdc7adbc90d6c8eb2cacb1bc34825374424  ./accesspath.py
+28f2a3b43403ecf179685aee9adafb65f5bc8a340314aa8d4cf36b8a1f00b7bc  ./configs/accessibility_mask_prompts_e5_v2.json
+9372af9c530a594e9355944829aca2723ad270fe95716caaeaa191e820b7c0e7  ./configs/accessibility_stairs_outdoor_no_occlusion_prompts.json
+cac568cf2b332471ce5d2a3ceaae4f460882322d80b8f00c40c7c1c813bebf2a  ./configs/accessibility_taxonomy.json
+7b2f950655ee26db6f7134c4f75ee87548603132f69375dd163617252b5f6c61  ./docs/DEPENDENCIES_AND_WEIGHTS.md
+69cb8637ad32704c9c30df9ad6d529350e205bd62aa3d3a8b66460cb3a326763  ./docs/REPRODUCIBLE_PIPELINE.md
+1c93d6a102763a352f8e4bc17fd36946dbc8bdd8f7a98ef71644506184311ec1  ./docs/SOURCE_MANIFEST.md
+a1be042986b949b43c9439e5a2e4bf06f8c44296f64f93231b9ebf5982c3e141  ./.gitignore
+3204ccc802a3d1fd983b1157acc28788f32e202b0f90af0e6ce82e002415d1c0  ./README.md
+2a3b1c478474d1cba76823f19dc506deb9c30915ca8633bd7937bddeb0a5e7dd  ./requirements/runtime.txt
+05b36802d29098a9ed1bb9e2f8391781f5ae70ccdad359241a961e2f9ee15bb1  ./slurm/run_accesspath_demo.sbatch
+abf0e66126a0c36c88e4b27977c3233c56c6672e69579fe5e25a7a53010ec38d  ./THIRD_PARTY_NOTICES.md
+5cff25d3577e68bace79480268b531d3f1578e0b3f8f7ac5e41031b111a1e2a9  ./tools/accessibility_2d_completion.py
+5f51907ecc5e3de1f86ce2649bcac0c584430a43b157f1eb9f612af831091570  ./tools/accessibility_3d_completion.py
+1f525525bf318f32ba7773d3a8cf1f4be0cc5c146de72f4f47f099f1dcf1c9b5  ./tools/accessibility_3d_variants.py
+adceb94323890674b9252f4349e1f6274d825584ff6556cd5bf65cc95b074f14  ./tools/accessibility_amodal_mask.py
+acf495884dc154ff4d9e6c0969426b478c591cfd9b23e0b53cec3959780ce21d  ./tools/accessibility_fast_2d_baseline.py
+98f34cd0710206e11e82d383147a9df9d83bb4cedd37aea187c4185d3a170f38  ./tools/accessibility_mask_proposals.py
+84fe82f2e16e296d0f79c640d54122a1d91c031d9ddd2c9037dae833fc0c9595  ./tools/audit_accessibility_3d_candidate.py
+3702ac02c658dc70106890ffeea47260d34a7270298f34989eb749de73f06a1a  ./tools/build_accessibility_review_bundle.py
+9692cbff8beeea2ed800054a5cf6b1140352c011195d3778228c9875da1bceaa  ./tools/build_accessibility_solid_mesh_showcase.py
+056a87a9cf9dc6e46884e2539a546a7e86a4fe8dd6d735bcff5a9392146a726f  ./tools/render_accessibility_turntable.py
+f7480d500f9cd07efc3224b258f126ac6baa92d4a5a01373efaf01a6616ab1e6  ./tools/sanitize_log_stream.py
+9bcff66ab4e0afa11ff4a4985bbdff7492e5e6ad68e6031cde420743cccba6e5  ./tools/sanitize_output_metadata.py
+06130da821e8e2578bcd243c84cef03fc6c8e56f3727d44472bd0f70e4615bab  ./tools/train_accessibility_amodal_adapter.py
+9e2085f3fdefc2672da5c71547afe3e24a511aa9d4dda622f3bf0708dfdb15a5  ./tools/update_accessibility_inference_progress.py
+96f20519960ad84050e5bfe84206c0f3ee78de27792ee1441c15c555a6165ab0  ./tools/validate_accessibility_reviewed_visible_workspace.py

configs/accessibility_mask_prompts_e5_v2.json

@@ -0,0 +1,134 @@
+{
+  "schema_version": "2.0",
+  "repair_basis": "Frozen before the E5 v2 rerun from pre-existing project repair and reannotation prompt inventories; v1 outputs are retained.",
+  "categories": {
+    "stairs": {
+      "prompts": [
+        "stair steps",
+        "outdoor staircase",
+        "concrete stair steps",
+        "stair treads",
+        "pedestrian stairway",
+        "steps at a building entrance"
+      ],
+      "max_area_ratio": 0.75
+    },
+    "ramp": {
+      "prompts": [
+        "wheelchair ramp",
+        "wheelchair access ramp",
+        "accessible ramp with handrails",
+        "accessible sloped walking surface",
+        "sloped sidewalk ramp",
+        "pedestrian access ramp"
+      ]
+    },
+    "tactile_paving": {
+      "prompts": [
+        "tactile walking surface indicator strip",
+        "raised bar tactile paving path",
+        "ribbed guidance tiles on pedestrian route",
+        "tactile guidance paving strip",
+        "tactile warning strip on sidewalk",
+        "truncated dome warning surface"
+      ],
+      "max_area_ratio": 0.65
+    },
+    "curb_cut": {
+      "prompts": [
+        "curb ramp",
+        "dropped curb",
+        "sidewalk curb cut",
+        "pedestrian curb ramp"
+      ]
+    },
+    "walkway": {
+      "prompts": [
+        "pedestrian sidewalk",
+        "walkable pedestrian path",
+        "accessible walkway",
+        "pavement area where pedestrians can walk"
+      ],
+      "max_area_ratio": 0.92
+    }
+  },
+  "category_confusions": {
+    "stairs": ["ramp"],
+    "ramp": ["stairs", "walkway"],
+    "tactile_paving": ["walkway"],
+    "curb_cut": ["ramp", "walkway"],
+    "walkway": ["stairs", "ramp"]
+  },
+  "obstacle_prompts": [
+    "person",
+    "wheelchair",
+    "baby stroller",
+    "dog",
+    "car",
+    "van",
+    "truck",
+    "bicycle",
+    "motorcycle",
+    "scooter",
+    "suitcase",
+    "trash bin",
+    "chair",
+    "table",
+    "bench",
+    "tree trunk",
+    "street sign",
+    "utility cabinet",
+    "traffic cone",
+    "bollard",
+    "pole",
+    "planter",
+    "box or package",
+    "construction material"
+  ],
+  "category_obstacle_prompts": {
+    "stairs": [
+      "object blocking the stairs",
+      "post blocking the stairs",
+      "railing post occluding the staircase"
+    ],
+    "ramp": [
+      "object blocking the ramp",
+      "post blocking the ramp"
+    ],
+    "curb_cut": [
+      "object blocking the curb ramp",
+      "street pole"
+    ],
+    "tactile_paving": [
+      "object on the tactile paving",
+      "street furniture"
+    ],
+    "walkway": [
+      "object blocking the walkway",
+      "street pole"
+    ]
+  },
+  "obstacle_maximum_area_ratio": {
+    "default": 0.20,
+    "person": 0.45,
+    "car": 0.55,
+    "van": 0.55,
+    "truck": 0.60
+  },
+  "barrier_obstacle_prompts": [
+    "temporary pedestrian barrier",
+    "construction safety barrier",
+    "road work barrier"
+  ],
+  "barrier_obstacle_backends": [
+    "sam3"
+  ],
+  "quality_thresholds": {
+    "minimum_target_area_ratio": 0.005,
+    "maximum_target_area_ratio": 0.92,
+    "minimum_prompt_agreement": 0.45,
+    "minimum_model_confidence": 0.45,
+    "auto_accept_score": 0.72,
+    "manual_review_score": 0.45
+  }
+}

configs/accessibility_stairs_outdoor_no_occlusion_prompts.json

@@ -0,0 +1,28 @@
+{
+  "categories": {
+    "stairs": {
+      "prompts": [
+        "outdoor stone staircase",
+        "historic masonry stair steps",
+        "visible walking treads of an outdoor staircase",
+        "pedestrian stairway steps, excluding handrails and side walls"
+      ],
+      "max_area_ratio": 0.45
+    }
+  },
+  "category_confusions": {
+    "stairs": []
+  },
+  "obstacle_prompts": [],
+  "category_obstacle_prompts": {},
+  "barrier_obstacle_prompts": [],
+  "barrier_obstacle_backends": [],
+  "quality_thresholds": {
+    "minimum_target_area_ratio": 0.01,
+    "maximum_target_area_ratio": 0.45,
+    "minimum_prompt_agreement": 0.45,
+    "minimum_model_confidence": 0.45,
+    "auto_accept_score": 0.72,
+    "manual_review_score": 0.45
+  }
+}

configs/accessibility_taxonomy.json

@@ -0,0 +1,84 @@
+{
+  "categories": {
+    "stairs": {
+      "display_name": "Stairs",
+      "geometry_model": "tread_riser_block",
+      "primary_users": ["mobility_impairment", "blind_or_low_vision"],
+      "surface_role": "level_change_barrier",
+      "risk_metrics": ["step_edge_continuity", "riser_height_consistency", "handrail_or_obstacle_clearance"],
+      "annotation_priority": ["target_visible", "target_amodal", "hidden", "obstacle", "stair_edges_y"],
+      "notes": "Use category-specific tread and riser geometry. Do not treat stairs as one smooth ramp."
+    },
+    "ramp": {
+      "display_name": "Accessible Ramp",
+      "geometry_model": "sloped_prism",
+      "primary_users": ["wheelchair_user", "walker_user", "mobility_impairment"],
+      "surface_role": "accessible_level_change",
+      "risk_metrics": ["slope", "cross_slope", "landing_continuity", "side_edge_clearance"],
+      "annotation_priority": ["target_visible", "target_amodal", "hidden", "obstacle", "ramp_edges"],
+      "notes": "Fit a continuous sloped surface and solidify as a ramp prism with side caps."
+    },
+    "tactile_paving": {
+      "display_name": "Tactile Paving",
+      "geometry_model": "surface_attachment_ribs_or_domes",
+      "primary_users": ["blind_or_low_vision"],
+      "surface_role": "navigation_cue",
+      "risk_metrics": ["pattern_direction", "pattern_periodicity", "warning_surface_coverage", "continuity_under_occlusion"],
+      "annotation_priority": ["target_visible", "target_amodal", "hidden", "obstacle", "pattern_type"],
+      "notes": "Reconstruct as shallow raised dots/ribs attached to a walkway or ramp base surface, not as a standalone thick body."
+    },
+    "curb_cut": {
+      "display_name": "Curb Cut",
+      "geometry_model": "curb_ramp_prism",
+      "primary_users": ["wheelchair_user", "walker_user", "mobility_impairment"],
+      "surface_role": "street_sidewalk_transition",
+      "risk_metrics": ["curb_transition_height", "ramp_slope", "gutter_alignment", "truncated_dome_presence"],
+      "annotation_priority": ["target_visible", "target_amodal", "hidden", "obstacle", "curb_edges"],
+      "notes": "Model as a local ramp transition between sidewalk and roadway, often with tactile warning surface."
+    },
+    "raised_curb": {
+      "display_name": "Raised Curb",
+      "geometry_model": "raised_curb_prism",
+      "primary_users": ["wheelchair_user", "walker_user", "blind_or_low_vision", "mobility_impairment"],
+      "surface_role": "non_walkable_level_change_barrier",
+      "risk_metrics": ["curb_height", "top_edge_continuity", "vertical_face_continuity", "route_clearance"],
+      "annotation_priority": ["target_visible", "target_amodal", "hidden", "obstacle", "curb_top_edge", "curb_base_edge"],
+      "notes": "Model as one continuous raised prism with a top surface and vertical face. Never infer repeated stair treads or a sawtooth profile."
+    },
+    "walkway": {
+      "display_name": "Walkway / Flat Ground",
+      "geometry_model": "flat_or_low_slope_slab",
+      "primary_users": ["wheelchair_user", "walker_user", "blind_or_low_vision"],
+      "surface_role": "travel_path",
+      "risk_metrics": ["surface_continuity", "clear_width", "obstacle_clearance", "roughness"],
+      "annotation_priority": ["target_visible", "target_amodal", "hidden", "obstacle"],
+      "notes": "Use a continuous slab or low-slope plane. Keep tactile paving as a separate overlay category when present."
+    }
+  },
+  "user_groups": {
+    "wheelchair_user": {
+      "requires": ["ramp", "curb_cut", "walkway"],
+      "high_risk_categories": ["stairs", "raised_curb", "curb_cut", "ramp"]
+    },
+    "walker_user": {
+      "requires": ["ramp", "curb_cut", "walkway"],
+      "high_risk_categories": ["stairs", "raised_curb", "walkway"]
+    },
+    "blind_or_low_vision": {
+      "requires": ["tactile_paving", "curb_cut", "stairs", "walkway"],
+      "high_risk_categories": ["tactile_paving", "stairs", "raised_curb", "curb_cut"]
+    },
+    "mobility_impairment": {
+      "requires": ["ramp", "curb_cut", "walkway", "stairs"],
+      "high_risk_categories": ["stairs", "raised_curb", "ramp", "curb_cut"]
+    }
+  },
+  "dataset_policy": {
+    "split_by_category": true,
+    "split_by_user_group": true,
+    "allow_multi_label": true,
+    "gold_for_training": false,
+    "automatic_category_is_ground_truth": false,
+    "automatic_mask_is_ground_truth": false
+  }
+}

docs/DEPENDENCIES_AND_WEIGHTS.md

@@ -0,0 +1,309 @@
+# Dependencies, attribution, and weight downloads
+
+This guide is written for a first-time user. AccessPath is inspired by and
+adapted from prior work on amodal completion, segmentation, geometry, and
+visual 3D reconstruction. It explains both **what is actually used at runtime**
+and **what is only cited or retained as an optional comparison**. Do not
+download a model merely because its name occurs in a related-work note.
+
+## 1. What AccessPath implements
+
+AccessPath implements an accessibility-focused workflow inspired by these
+research directions, while adding project-level adaptation around external
+models:
+
+1. prompt selection and target/obstacle mask proposal orchestration;
+2. constrained visible/hidden/amodal mask construction and validation;
+3. mask-restricted 2D inpainting candidate generation and selection;
+4. depth/geometry diagnostics, quality gates, rendering, and review bundles;
+5. an adapter that sends an RGB image plus a three-value mask to an external
+   visual-3D backend.
+
+It does **not** claim authorship of SAM 3, Stable Diffusion, Depth Anything V2,
+VGGT, Amodal3R, TRELLIS, pix2gestalt, Open-World AMODAL, or Amodal Completion
+in the Wild. Where one of these is a runtime backend, its code, license, and
+weights remain separate; where it is listed as related work, AccessPath does
+not import or execute it.
+
+## 2. Exact dependency status
+
+| Method/model | Status in this repository | Where in AccessPath | What a user must do |
+| --- | --- | --- | --- |
+| [SAM 3](https://github.com/facebookresearch/sam3) | Used by the automatic mask-proposal stage. | `tools/accessibility_mask_proposals.py` | Install it in its own environment and request access to [`facebook/sam3`](https://huggingface.co/facebook/sam3). |
+| [Stable Diffusion inpainting](https://huggingface.co/sd-legacy/stable-diffusion-inpainting) | Used by the default GPU 2D completion stage. | `tools/accessibility_2d_completion.py` | Download an inpainting checkpoint under its own terms. |
+| [Depth Anything V2](https://github.com/DepthAnything/Depth-Anything-V2) | Used by the default full-pipeline depth/geometry diagnostic. | `accessibilityamodal/depth.py` | Install the official repository and download the selected checkpoint. |
+| [Amodal3R](https://sm0kywu.github.io/Amodal3R/) | Used by the default visual 3D stage through a thin adapter. | `tools/accessibility_3d_completion.py` | Install the official runtime and obtain its model assets. |
+| [TRELLIS image large](https://huggingface.co/microsoft/TRELLIS-image-large) | Upstream dependency reported by the Amodal3R model card. | External Amodal3R runtime | Obtain it only following the upstream Amodal3R instructions. |
+| [VGGT](https://github.com/facebookresearch/vggt) | **Optional** depth/point-map engine; not selected by the default Slurm launcher. | `accessibilityamodal/depth.py` | Install/download only when running `--depth-engine vggt`. |
+| [pix2gestalt](https://github.com/cvlab-columbia/pix2gestalt) | **Not executed.** Kept only as a related-work/comparison URL in a baseline manifest. | `tools/accessibility_fast_2d_baseline.py` | No installation or checkpoint is required for AccessPath. |
+| [Open-World AMODAL](https://github.com/saraao/amodal) | **Not executed.** Kept only as a related-work/comparison URL. | `tools/accessibility_fast_2d_baseline.py` | No installation or checkpoint is required for AccessPath. |
+| [Amodal Completion in the Wild](https://github.com/Championchess/Amodal-Completion-in-the-Wild) | **Not executed.** Mentioned as a compatible external research backend only. | `accessibilityamodal/pipeline.py` | No installation or checkpoint is required for AccessPath. |
+
+Therefore, no pix2gestalt, Open-World AMODAL, or Amodal-Wild code/weights are
+needed for the commands in this repository. Their links are present so readers
+can distinguish the accessibility-adapted AccessPath workflow from related
+amodal-completion work.
+
+## 3. Before starting
+
+You need Linux, Git, Python, a CUDA-capable GPU, and a Slurm installation for
+the all-in-one `pipeline` command. The direct `2d` and `3d` commands can be
+run outside Slurm, but still need a compatible CUDA environment.
+
+Clone the anonymous release:
+
+```bash
+git clone https://huggingface.co/anonymous-accesspath/AccessPath
+cd AccessPath
+```
+
+Create a general utility environment. Install the PyTorch build that matches
+your CUDA driver using the [official PyTorch selector](https://pytorch.org/get-started/locally/),
+then install the Python packages used by the project wrappers:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+# Install a CUDA-compatible PyTorch build here, following pytorch.org.
+python -m pip install -r requirements/runtime.txt
+python -m pip install diffusers transformers accelerate safetensors huggingface_hub
+```
+
+Do not place downloaded checkpoints inside the Git clone. Keep them in a
+separate local `models/` directory and pass their paths through environment
+variables. This avoids accidentally committing large or license-restricted
+files.
+
+## 4. Download each runtime asset
+
+### 4.1 SAM 3: mask proposals
+
+SAM 3 is used only to propose a visible target mask and an obstacle mask. The
+proposal is not ground truth; inspect it before using it for an experiment.
+
+1. Read and accept the access terms on [`facebook/sam3`](https://huggingface.co/facebook/sam3).
+2. Follow the official [SAM 3 installation guide](https://github.com/facebookresearch/sam3).
+   SAM 3 may require a newer Python/PyTorch/CUDA combination than the remaining
+   pipeline, so a dedicated environment is recommended.
+3. Authenticate and download the official files:
+
+```bash
+hf auth login
+hf download facebook/sam3 sam3.pt config.json --local-dir /path/to/models/sam3
+```
+
+4. Record the environment and paths for AccessPath:
+
+```bash
+export SAM3_PYTHON=/path/to/sam3-environment/bin/python
+export SAM3_REPO=/path/to/sam3-source
+export SAM3_CHECKPOINT=/path/to/models/sam3/sam3.pt
+```
+
+### 4.2 Stable Diffusion: 2D inpainting
+
+The 2D stage calls Diffusers' inpainting pipeline. Obtain an inpainting model
+from [`sd-legacy/stable-diffusion-inpainting`](https://huggingface.co/sd-legacy/stable-diffusion-inpainting)
+or use another compatible checkpoint only after checking its model card and
+license. A typical download is:
+
+```bash
+hf download sd-legacy/stable-diffusion-inpainting \
+  --local-dir /path/to/models/stable-diffusion-inpainting
+export SD_MODEL=/path/to/models/stable-diffusion-inpainting
+```
+
+The 2D implementation changes only the reviewed completion envelope and saves
+its selected result plus metadata under the requested output directory.
+
+### 4.3 Depth Anything V2: depth and geometry diagnostics
+
+The default full launcher expects the large indoor metric checkpoint:
+[`Depth-Anything-V2-Metric-Hypersim-Large`](https://huggingface.co/depth-anything/Depth-Anything-V2-Metric-Hypersim-Large).
+Install source code from the official [Depth Anything V2 repository](https://github.com/DepthAnything/Depth-Anything-V2), then download the exact checkpoint:
+
+```bash
+git clone https://github.com/DepthAnything/Depth-Anything-V2 /path/to/Depth-Anything-V2
+hf download depth-anything/Depth-Anything-V2-Metric-Hypersim-Large \
+  depth_anything_v2_metric_hypersim_vitl.pth \
+  --local-dir /path/to/models/depth-anything-v2-metric-hypersim-large
+
+export DEPTH_REPO=/path/to/Depth-Anything-V2
+export DEPTH_CHECKPOINT=/path/to/models/depth-anything-v2-metric-hypersim-large/depth_anything_v2_metric_hypersim_vitl.pth
+```
+
+Depth output is a diagnostic estimate. It is not automatically calibrated
+metric ground truth for the input camera and must not be treated as a
+navigation-safety measurement.
+
+### 4.4 Amodal3R and TRELLIS: visual 3D completion
+
+AccessPath does not redistribute Amodal3R source code or weights. The adapter
+requires an external Python environment where this import succeeds:
+
+```bash
+python -c "from amodal3d.pipelines import Amodal3RImageTo3DPipeline; print('Amodal3R runtime ready')"
+```
+
+Use the official [Amodal3R project page](https://sm0kywu.github.io/Amodal3R/),
+[model card](https://huggingface.co/Sm0kyWu/Amodal3R), and
+[paper](https://arxiv.org/abs/2503.13439) for installation and license terms.
+The model card states that its implementation is built on TRELLIS and obtains
+pretrained assets from [`microsoft/TRELLIS-image-large`](https://huggingface.co/microsoft/TRELLIS-image-large).
+For a local snapshot of the published model card repository:
+
+```bash
+hf download Sm0kyWu/Amodal3R --local-dir /path/to/models/Amodal3R
+```
+
+Follow the upstream project instructions for any additional TRELLIS assets and
+CUDA rasterizer dependencies. Then configure AccessPath:
+
+```bash
+export AMODAL3D_PYTHON=/path/to/amodal3r-environment/bin/python
+export AMODAL3D_MODEL=/path/to/models/Amodal3R
+export AMODAL3D_TORCH_HOME=/path/to/model-cache/torch
+```
+
+The 3D result is a learned visual reconstruction. It is not guaranteed to be
+metric, watertight, scale-calibrated, or safe for path-planning decisions.
+
+### 4.5 Optional VGGT geometry route
+
+VGGT is implemented as an optional `--depth-engine vggt` route. It is useful
+for comparing a geometry/point-map estimate, but it is **not** the default
+AccessPath visual-3D output and it is not required for the default full run.
+
+```bash
+git clone https://github.com/facebookresearch/vggt /path/to/vggt
+python -m pip install -r /path/to/vggt/requirements.txt
+hf download facebook/VGGT-1B --local-dir /path/to/models/VGGT-1B
+```
+
+Then invoke the diagnostic engine with `--depth-engine vggt`, pass
+`--vggt-repo /path/to/vggt`, and use `--vggt-model /path/to/models/VGGT-1B`.
+See the [official VGGT repository](https://github.com/facebookresearch/vggt)
+and [model page](https://huggingface.co/facebook/VGGT-1B) for current access,
+license, and checkpoint conditions.
+
+### 4.6 Project amodal-mask adapter checkpoint
+
+`AMODAL_CHECKPOINT` is an AccessPath-trained mask-adapter checkpoint, not an
+upstream public dependency. It is deliberately withheld during anonymous
+review. Its release requires confirmation of training-data permissions,
+base-model terms, privacy review, and the paper's release policy.
+
+Without this checkpoint, the **all-in-one** `pipeline` command stops at its
+preflight check. Readers can still run the direct 2D and visual-3D commands
+with their own reviewed masks. This limitation is intentional and explicit;
+the repository does not substitute a different checkpoint silently.
+
+## 5. Run the three supported routes
+
+### Route A — direct 2D completion
+
+Prepare an RGB image and three aligned binary masks: visible target, complete
+amodal target, and obstacle. All must have the same width and height as the
+RGB image.
+
+```bash
+python accesspath.py 2d -- \
+  --image inputs/scene.jpg \
+  --target-visible-mask inputs/target_visible.png \
+  --target-amodal-mask inputs/target_amodal.png \
+  --obstacle-mask inputs/obstacle.png \
+  --category stairs \
+  --model "$SD_MODEL" \
+  --output-dir outputs/stairs_2d \
+  --device cuda
+```
+
+Inspect the selected RGB and the JSON manifest under `outputs/stairs_2d`.
+
+### Route B — direct visual 3D completion
+
+Create one three-value mask at the RGB resolution: `255` is background, `188`
+is visible target, and `0` is hidden target. Then run:
+
+```bash
+AMODAL3D_TORCH_HOME="$AMODAL3D_TORCH_HOME" \
+"$AMODAL3D_PYTHON" tools/accessibility_3d_completion.py \
+  --image inputs/scene.jpg \
+  --mask inputs/amodal_3value.png \
+  --model "$AMODAL3D_MODEL" \
+  --output-dir outputs/stairs_3d
+```
+
+Inspect the generated manifest and image/mesh assets. Do not interpret a
+plausible-looking 3D asset as a physical measurement.
+
+### Route C — full Slurm pipeline
+
+After configuring every required variable above, submit a finite one-image job:
+
+```bash
+python accesspath.py pipeline -- \
+  --image inputs/scene.jpg \
+  --category stairs \
+  --output-dir outputs/stairs_full
+```
+
+The command submits one GPU job, waits by default, saves its results, and exits
+when the job terminates. Add `--no-wait` to return after submission. The output
+review order is documented in [REPRODUCIBLE_PIPELINE.md](REPRODUCIBLE_PIPELINE.md).
+
+## 6. Citation and related-work links
+
+Use the official paper/model pages below when citing an external dependency.
+
+```bibtex
+@article{wu2025amodal3r,
+  title={Amodal3R: Amodal 3D Reconstruction from Occluded 2D Images},
+  author={Wu, Tianhao and Zheng, Chuanxia and Guan, Frank and Vedaldi, Andrea and Cham, Tat-Jen},
+  journal={arXiv preprint arXiv:2503.13439},
+  year={2025}
+}
+
+@inproceedings{wang2025vggt,
+  title={VGGT: Visual Geometry Grounded Transformer},
+  author={Wang, Jianyuan and Chen, Minghao and Karaev, Nikita and Vedaldi, Andrea and Rupprecht, Christian and Novotny, David},
+  booktitle={CVPR},
+  year={2025}
+}
+
+@inproceedings{ozguroglu2024pix2gestalt,
+  title={pix2gestalt: Amodal Segmentation by Synthesizing Wholes},
+  author={Ozguroglu, Ege and others},
+  booktitle={CVPR},
+  year={2024}
+}
+
+@inproceedings{ao2025open,
+  title={Open-World Amodal Appearance Completion},
+  author={Ao, Jiayang and Jiang, Yanbei and Ke, Qiuhong and Ehinger, Krista A.},
+  booktitle={CVPR},
+  year={2025}
+}
+
+@inproceedings{zhan2024amodal,
+  title={Amodal Ground Truth and Completion in the Wild},
+  author={Zhan, Guanqi and Zheng, Chuanxia and Xie, Weidi and Zisserman, Andrew},
+  booktitle={CVPR},
+  year={2024}
+}
+
+@article{yang2024depthanythingv2,
+  title={Depth Anything V2},
+  author={Yang, Lihe and others},
+  journal={arXiv:2406.09414},
+  year={2024}
+}
+```
+
+For convenience, the canonical links are: [Amodal3R paper](https://arxiv.org/abs/2503.13439),
+[VGGT paper](https://arxiv.org/abs/2503.11651),
+[pix2gestalt paper](https://arxiv.org/abs/2401.14398),
+[Open-World AMODAL paper](https://arxiv.org/abs/2411.13019),
+[Amodal Completion in the Wild paper](https://arxiv.org/abs/2312.17247), and
+[Depth Anything V2 paper](https://arxiv.org/abs/2406.09414).

docs/REPRODUCIBLE_PIPELINE.md

@@ -0,0 +1,69 @@
+# 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.

docs/SOURCE_MANIFEST.md

@@ -0,0 +1,22 @@
+# Source manifest
+
+This file maps every execution stage to its implementation so anonymous
+reviewers can trace the running pipeline without unrelated development files.
+
+| Stage | Primary implementation |
+| --- | --- |
+| Command submission, polling, portable paths | `accesspath.py`, `accesspath3r/cli.py`, `accesspath3r/privacy.py` |
+| Finite GPU allocation and stage orchestration | `slurm/run_accesspath_demo.sbatch` |
+| Target/obstacle mask proposal | `tools/accessibility_mask_proposals.py`, `configs/accessibility_mask_prompts_e5_v2.json` |
+| Reviewed-mask validation and amodal-mask proposal | `tools/validate_accessibility_reviewed_visible_workspace.py`, `tools/accessibility_amodal_mask.py`, `tools/train_accessibility_amodal_adapter.py` |
+| GPU visual 2D completion | `tools/accessibility_2d_completion.py`, `accessibilityamodal/visual_completion.py` |
+| Deterministic 2D comparison baseline | `tools/accessibility_fast_2d_baseline.py` |
+| Depth, geometry, mask refinement, and checks | `accessibilityamodal/depth.py`, `accessibilityamodal/reconstruct.py`, `accessibilityamodal/geometry_analysis.py`, `accessibilityamodal/pipeline.py`, `accessibilityamodal/sam_refinement.py`, `accessibilityamodal/verification.py` |
+| Visual 3D backend adapter | `tools/accessibility_3d_completion.py` |
+| 3D diagnostics and rendering | `tools/accessibility_3d_variants.py`, `tools/build_accessibility_solid_mesh_showcase.py`, `tools/render_accessibility_turntable.py` |
+| Quality reports, compact review bundle, and metadata sanitization | `tools/audit_accessibility_3d_candidate.py`, `tools/build_accessibility_review_bundle.py`, `tools/update_accessibility_inference_progress.py`, `tools/sanitize_log_stream.py`, `tools/sanitize_output_metadata.py` |
+
+No upstream Amodal3R source, model checkpoint, source image, annotation mask,
+training run, experiment log, local environment, or author-identifying file is
+included. Upstream model attribution is retained in
+[THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md).

requirements/runtime.txt

@@ -0,0 +1,6 @@
+numpy
+pillow
+opencv-python
+imageio
+trimesh
+gradio_client

slurm/run_accesspath_demo.sbatch

@@ -0,0 +1,573 @@
+#!/usr/bin/env bash
+#SBATCH -J acc-single-demo
+#SBATCH -p 5090
+#SBATCH -G 1
+#SBATCH -c 8
+#SBATCH --mem=64G
+#SBATCH -t 04:00:00
+#SBATCH -o Logs/slurm-%j.out
+#SBATCH -e Logs/slurm-%j.err
+
+set -euo pipefail
+mkdir -p Logs
+
+PROJECT_DIR="${PROJECT_DIR:-${SLURM_SUBMIT_DIR:-$PWD}}"
+IMAGE="${IMAGE:?Set IMAGE=/absolute/or/project-relative/image.jpg}"
+CATEGORY="${CATEGORY:-walkway}"
+SAMPLE_ID="${SAMPLE_ID:-}"
+OUTPUT_DIR="${OUTPUT_DIR:-$PROJECT_DIR/output/inference/$SLURM_JOB_ID}"
+ACCESSIBILITY3D_DIR="$OUTPUT_DIR/accessibility3d"
+RUN_GPU_2D="${RUN_GPU_2D:-${RUN_SD_2D:-1}}"
+RUN_FAST_2D="${RUN_FAST_2D:-0}"
+ALLOW_LARGE_2D="${ALLOW_LARGE_2D:-0}"
+RUN_DEPTH="${RUN_DEPTH:-1}"
+RUN_AMODAL3D_3D="${RUN_ACCESSIBILITYAMODAL_VISUAL_3D:-${RUN_AMODAL3D_3D:-1}}"
+RUN_AMODAL3D_GLB="${EXPORT_ACCESSIBILITYAMODAL_VISUAL_GLB:-${RUN_AMODAL3D_GLB:-0}}"
+NO_TARGET_OCCLUDER="${NO_TARGET_OCCLUDER:-0}"
+REVIEWED_VISIBLE_WORKSPACE="${REVIEWED_VISIBLE_WORKSPACE:-}"
+
+SAM3_PYTHON="${SAM3_PYTHON:-$PROJECT_DIR/.envs/sam3/bin/python}"
+AMODAL3D_PYTHON="${AMODAL3D_PYTHON:-$PROJECT_DIR/.envs/amodal3d/bin/python}"
+SAM3_REPO="${SAM3_REPO:-$PROJECT_DIR/repos/sam3}"
+SAM3_CHECKPOINT="${SAM3_CHECKPOINT:-$PROJECT_DIR/weights/sam3/sam3.pt}"
+AMODAL_CHECKPOINT="${AMODAL_CHECKPOINT:-$PROJECT_DIR/weights/accessibility_amodal_adapter/best.pt}"
+DEPTH_REPO="${DEPTH_REPO:-$PROJECT_DIR/repos/Depth-Anything-V2}"
+DEPTH_CHECKPOINT="${DEPTH_CHECKPOINT:-$PROJECT_DIR/weights/depth_anything_v2_metric_hypersim_vitl.pth}"
+PROMPT_CONFIG="${PROMPT_CONFIG:-}"
+if [[ -z "$PROMPT_CONFIG" ]]; then
+  if [[ "$NO_TARGET_OCCLUDER" == "1" && "$CATEGORY" == "stairs" ]]; then
+    PROMPT_CONFIG="$PROJECT_DIR/configs/accessibility_stairs_outdoor_no_occlusion_prompts.json"
+  else
+    # Unified prompt bank: SAM3 decides which target/occluder concepts are
+    # present in the image; callers do not need to classify the scene first.
+    PROMPT_CONFIG="$PROJECT_DIR/configs/accessibility_mask_prompts_e5_v2.json"
+  fi
+fi
+SD_MODEL="${SD_MODEL:-$PROJECT_DIR/weights/stable-diffusion-inpainting}"
+AMODAL3D_MODEL="${AMODAL3D_MODEL:-$PROJECT_DIR/weights/Amodal3R}"
+AMODAL3D_TORCH_HOME="${AMODAL3D_TORCH_HOME:-$PROJECT_DIR/weights/torch}"
+LOG_SANITIZER="$PROJECT_DIR/tools/sanitize_log_stream.py"
+METADATA_SANITIZER="$PROJECT_DIR/tools/sanitize_output_metadata.py"
+VERIFICATION_TOOL="$PROJECT_DIR/tools/audit_accessibility_3d_candidate.py"
+REVIEWED_VISIBLE_VALIDATOR="$PROJECT_DIR/tools/validate_accessibility_reviewed_visible_workspace.py"
+GPU_TURNTABLE_TOOL="$PROJECT_DIR/tools/render_accessibility_turntable.py"
+REVIEW_BUNDLE_TOOL="$PROJECT_DIR/tools/build_accessibility_review_bundle.py"
+
+# Keep workstation usernames, home prefixes, and external paths out of the
+# persistent Slurm logs. Python warnings and tracebacks pass through this too.
+privacy_filter_args=(
+  --project-root "$PROJECT_DIR"
+  --output-root "$OUTPUT_DIR"
+  --sensitive-path "$IMAGE"
+  --sensitive-path "$PROMPT_CONFIG"
+  --sensitive-path "$SAM3_PYTHON"
+  --sensitive-path "$AMODAL3D_PYTHON"
+  --sensitive-path "$SAM3_REPO"
+  --sensitive-path "$SAM3_CHECKPOINT"
+  --sensitive-path "$AMODAL_CHECKPOINT"
+  --sensitive-path "$DEPTH_REPO"
+  --sensitive-path "$DEPTH_CHECKPOINT"
+  --sensitive-path "$SD_MODEL"
+  --sensitive-path "$AMODAL3D_MODEL"
+  --sensitive-path "$AMODAL3D_TORCH_HOME"
+)
+if [[ -n "$REVIEWED_VISIBLE_WORKSPACE" ]]; then
+  privacy_filter_args+=(--sensitive-path "$REVIEWED_VISIBLE_WORKSPACE")
+fi
+LOG_FILTER_PYTHON="$AMODAL3D_PYTHON"
+if [[ ! -x "$LOG_FILTER_PYTHON" ]]; then
+  LOG_FILTER_PYTHON="$(command -v python3 || true)"
+fi
+if [[ -n "$LOG_FILTER_PYTHON" ]] && [[ -f "$LOG_SANITIZER" ]]; then
+  exec > >("$LOG_FILTER_PYTHON" "$LOG_SANITIZER" "${privacy_filter_args[@]}")
+  exec 2> >("$LOG_FILTER_PYTHON" "$LOG_SANITIZER" "${privacy_filter_args[@]}" >&2)
+fi
+
+module load cuda/13.0 || true
+
+case "$CATEGORY" in
+  curb_cut|ramp|stairs|tactile_paving|walkway) ;;
+  *) echo "Unsupported CATEGORY=$CATEGORY" >&2; exit 2 ;;
+esac
+
+if ! cd "$PROJECT_DIR" 2>/dev/null; then
+  echo "Could not enter the configured project directory." >&2
+  exit 2
+fi
+[[ -f "$IMAGE" ]] || { echo "The configured input image was not found." >&2; exit 2; }
+IMAGE="$(realpath "$IMAGE")"
+if [[ -z "$SAMPLE_ID" ]]; then
+  SAMPLE_ID="$(basename "$IMAGE")"
+  SAMPLE_ID="${SAMPLE_ID%.*}"
+  SAMPLE_ID="${SAMPLE_ID//[^A-Za-z0-9_-]/_}"
+fi
+
+[[ -x "$AMODAL3D_PYTHON" ]] || { echo "The Accessibility3D Python environment is missing." >&2; exit 2; }
+for tool_path in "$VERIFICATION_TOOL" "$GPU_TURNTABLE_TOOL" "$REVIEW_BUNDLE_TOOL"; do
+  [[ -f "$tool_path" ]] || { echo "A required AccessibilityAmodal tool is missing." >&2; exit 2; }
+done
+[[ -e "$AMODAL_CHECKPOINT" ]] || { echo "The amodal-mask runtime asset is missing." >&2; exit 2; }
+if [[ -n "$REVIEWED_VISIBLE_WORKSPACE" ]]; then
+  [[ -d "$REVIEWED_VISIBLE_WORKSPACE" ]] || { echo "The reviewed-visible workspace is missing." >&2; exit 2; }
+  [[ -f "$REVIEWED_VISIBLE_VALIDATOR" ]] || { echo "The reviewed-visible validator is missing." >&2; exit 2; }
+else
+  [[ -x "$SAM3_PYTHON" ]] || { echo "The SAM3 Python environment is missing." >&2; exit 2; }
+  for path in "$SAM3_REPO" "$SAM3_CHECKPOINT"; do
+    [[ -e "$path" ]] || { echo "A required SAM3 runtime asset is missing." >&2; exit 2; }
+  done
+fi
+if [[ "$RUN_DEPTH" == "1" ]]; then
+  for path in "$DEPTH_REPO" "$DEPTH_CHECKPOINT"; do
+    [[ -e "$path" ]] || { echo "A required depth runtime asset is missing." >&2; exit 2; }
+  done
+fi
+if [[ "$RUN_GPU_2D" == "1" ]] && [[ ! -e "$SD_MODEL" ]]; then
+  echo "The Stable Diffusion inpainting model is missing." >&2
+  exit 2
+fi
+if [[ "$RUN_AMODAL3D_3D" == "1" ]]; then
+  for path in \
+    "$AMODAL3D_MODEL/pipeline.json" \
+    "$AMODAL3D_TORCH_HOME/hub/facebookresearch_dinov2_main"; do
+    [[ -e "$path" ]] || { echo "A required Accessibility3D runtime asset is missing." >&2; exit 2; }
+  done
+fi
+
+export JOB_TMPDIR="$TMPDIR/job-$SLURM_JOB_ID"
+export XDG_CACHE_HOME="$JOB_TMPDIR/xdg_cache"
+export HF_HOME="$JOB_TMPDIR/huggingface"
+export TORCH_HOME="$JOB_TMPDIR/torch"
+export TRITON_CACHE_DIR="$JOB_TMPDIR/triton"
+export MPLCONFIGDIR="$JOB_TMPDIR/matplotlib"
+export PYTHONNOUSERSITE=1
+mkdir -p "$JOB_TMPDIR" "$XDG_CACHE_HOME" "$HF_HOME" "$TORCH_HOME" \
+  "$TRITON_CACHE_DIR" "$MPLCONFIGDIR" "$OUTPUT_DIR"
+
+# These weights are seconds measured from a representative full stairs run on
+# the target GPU partition. They drive an approximate progress bar and ETA; actual
+# image complexity, cold model caches, and cluster load can change the timing.
+SAM3_WEIGHT=150
+if [[ -n "$REVIEWED_VISIBLE_WORKSPACE" ]]; then
+  SAM3_WEIGHT=5
+fi
+MASK_WEIGHT=13
+FAST_2D_WEIGHT=12
+GPU_2D_WEIGHT=40
+GEOMETRY_WEIGHT=24
+if [[ "$RUN_DEPTH" != "1" ]]; then
+  GEOMETRY_WEIGHT=6
+fi
+TURNTABLE_WEIGHT=3
+VARIANTS_WEIGHT=420
+AMODAL3D_WEIGHT=75
+if [[ "$RUN_AMODAL3D_GLB" == "1" ]]; then
+  # On the 1368x1824 9528 reference run, GPU UV/PBR baking added about nine
+  # minutes after the ordinary Gaussian and mesh renders had completed.
+  AMODAL3D_WEIGHT=615
+fi
+
+TOTAL_WEIGHT=$((SAM3_WEIGHT + MASK_WEIGHT + GEOMETRY_WEIGHT + TURNTABLE_WEIGHT + VARIANTS_WEIGHT))
+if [[ "$RUN_FAST_2D" == "1" ]]; then
+  TOTAL_WEIGHT=$((TOTAL_WEIGHT + FAST_2D_WEIGHT))
+fi
+if [[ "$RUN_GPU_2D" == "1" ]]; then
+  TOTAL_WEIGHT=$((TOTAL_WEIGHT + GPU_2D_WEIGHT))
+fi
+if [[ "$RUN_AMODAL3D_3D" == "1" ]]; then
+  TOTAL_WEIGHT=$((TOTAL_WEIGHT + AMODAL3D_WEIGHT))
+fi
+
+PROGRESS_FILE="$OUTPUT_DIR/progress.json"
+PROGRESS_WRITER="$PROJECT_DIR/tools/update_accessibility_inference_progress.py"
+COMPLETED_WEIGHT=0
+CURRENT_STAGE_KEY="initializing"
+CURRENT_STAGE_LABEL="Initializing GPU job"
+
+start_stage() {
+  local stage_key="$1"
+  local stage_label="$2"
+  local stage_weight="$3"
+  local start_percent end_percent
+  start_percent=$((COMPLETED_WEIGHT * 100 / TOTAL_WEIGHT))
+  end_percent=$(((COMPLETED_WEIGHT + stage_weight) * 100 / TOTAL_WEIGHT))
+  CURRENT_STAGE_KEY="$stage_key"
+  CURRENT_STAGE_LABEL="$stage_label"
+  "$AMODAL3D_PYTHON" "$PROGRESS_WRITER" \
+    --path "$PROGRESS_FILE" \
+    --status running \
+    --stage-key "$stage_key" \
+    --stage-label "$stage_label" \
+    --percent "$start_percent" \
+    --stage-end-percent "$end_percent" \
+    --stage-expected-seconds "$stage_weight" \
+    --total-estimated-seconds "$TOTAL_WEIGHT"
+}
+
+finish_stage() {
+  COMPLETED_WEIGHT=$((COMPLETED_WEIGHT + $1))
+}
+
+sanitize_output_metadata() {
+  if [[ -x "$AMODAL3D_PYTHON" ]] && [[ -f "$METADATA_SANITIZER" ]]; then
+    "$AMODAL3D_PYTHON" "$METADATA_SANITIZER" \
+      --root "$OUTPUT_DIR" \
+      --project-root "$PROJECT_DIR" \
+      --sensitive-path "$IMAGE" \
+      --sensitive-path "$PROMPT_CONFIG" \
+      --sensitive-path "$SAM3_PYTHON" \
+      --sensitive-path "$AMODAL3D_PYTHON" \
+      --sensitive-path "$SAM3_REPO" \
+      --sensitive-path "$SAM3_CHECKPOINT" \
+      --sensitive-path "$AMODAL_CHECKPOINT" \
+      --sensitive-path "$DEPTH_REPO" \
+      --sensitive-path "$DEPTH_CHECKPOINT" \
+      --sensitive-path "$SD_MODEL" \
+      --sensitive-path "$AMODAL3D_MODEL" \
+      --sensitive-path "$AMODAL3D_TORCH_HOME"
+  fi
+}
+
+record_exit() {
+  local exit_code=$?
+  if [[ "$exit_code" -ne 0 ]]; then
+    set +e
+    "$AMODAL3D_PYTHON" "$PROGRESS_WRITER" \
+      --path "$PROGRESS_FILE" \
+      --status failed \
+      --message "Stage failed: $CURRENT_STAGE_LABEL" \
+      --exit-code "$exit_code"
+  fi
+  sanitize_output_metadata
+}
+trap record_exit EXIT
+
+echo "Image: $IMAGE"
+echo "Category: $CATEGORY"
+echo "No target occluder mode: $NO_TARGET_OCCLUDER"
+echo "Reviewed visible workspace: ${REVIEWED_VISIBLE_WORKSPACE:-none}"
+echo "Sample ID: $SAMPLE_ID"
+echo "Output: $OUTPUT_DIR"
+echo "Estimated GPU runtime: about $(( (TOTAL_WEIGHT + 59) / 60 )) minutes (queue time excluded)"
+
+TARGET_VISIBLE_MASK=""
+OBSTACLE_CANDIDATE_MASK=""
+if [[ -n "$REVIEWED_VISIBLE_WORKSPACE" ]]; then
+  REVIEWED_VISIBLE_OUTPUT="$OUTPUT_DIR/01_reviewed_visible"
+  start_stage "reviewed_visible" "Validated human-reviewed visible target mask" "$SAM3_WEIGHT"
+  "$AMODAL3D_PYTHON" "$REVIEWED_VISIBLE_VALIDATOR" \
+    --workspace "$REVIEWED_VISIBLE_WORKSPACE" \
+    --image "$IMAGE" \
+    --sample-id "$SAMPLE_ID" \
+    --category "$CATEGORY" \
+    --output-dir "$REVIEWED_VISIBLE_OUTPUT"
+  finish_stage "$SAM3_WEIGHT"
+  TARGET_VISIBLE_MASK="$REVIEWED_VISIBLE_OUTPUT/target_visible.png"
+  OBSTACLE_CANDIDATE_MASK="$REVIEWED_VISIBLE_OUTPUT/obstacle.png"
+else
+  SAM3_OUTPUT="$OUTPUT_DIR/01_sam3"
+  start_stage "sam3" "SAM3 target and obstacle masks" "$SAM3_WEIGHT"
+  "$SAM3_PYTHON" tools/accessibility_mask_proposals.py \
+    --image "$IMAGE" \
+    --single-sample-id "$SAMPLE_ID" \
+    --single-category "$CATEGORY" \
+    --prompt-config "$PROMPT_CONFIG" \
+    --output-dir "$SAM3_OUTPUT" \
+    --backend sam3 \
+    --device cuda \
+    --artifact-level standard \
+    --sam3-repo "$SAM3_REPO" \
+    --sam3-checkpoint "$SAM3_CHECKPOINT"
+  finish_stage "$SAM3_WEIGHT"
+  SAM3_SAMPLE="$SAM3_OUTPUT/samples/$SAMPLE_ID"
+  TARGET_VISIBLE_MASK="$SAM3_SAMPLE/target_visible_candidate.png"
+  OBSTACLE_CANDIDATE_MASK="$SAM3_SAMPLE/obstacle.png"
+fi
+
+MASK_OUTPUT="$OUTPUT_DIR/02_masks"
+start_stage "amodal_masks" "Visible, hidden, amodal, and obstacle masks" "$MASK_WEIGHT"
+"$AMODAL3D_PYTHON" tools/accessibility_amodal_mask.py \
+  --image "$IMAGE" \
+  --target-visible-mask "$TARGET_VISIBLE_MASK" \
+  --obstacle-candidate-mask "$OBSTACLE_CANDIDATE_MASK" \
+  --category "$CATEGORY" \
+  --checkpoint "$AMODAL_CHECKPOINT" \
+  --output-dir "$MASK_OUTPUT" \
+  --device cuda
+finish_stage "$MASK_WEIGHT"
+
+# Do not turn a rejected SAM3 proposal into a polished but physically unrelated
+# 3D object.  The verifier records the evidence in a persistent JSON report;
+# a clean exit is intentional so the user can correct/re-prompt the masks.
+PREFLIGHT_DIR="$OUTPUT_DIR/05_quality_checks"
+PREFLIGHT_DECISION="$("$AMODAL3D_PYTHON" "$VERIFICATION_TOOL" \
+  --run-dir "$OUTPUT_DIR" \
+  --sample-id "$SAMPLE_ID" \
+  --category "$CATEGORY" \
+  --output "$PREFLIGHT_DIR/preflight.json" \
+  --preflight-only \
+  --print-decision)"
+echo "3D preflight decision: $PREFLIGHT_DECISION"
+if [[ "$PREFLIGHT_DECISION" != "accept" ]]; then
+  "$AMODAL3D_PYTHON" "$PROGRESS_WRITER" \
+    --path "$PROGRESS_FILE" \
+    --status completed \
+    --stage-key mask_gate \
+    --stage-label "3D withheld: re-prompt or review masks" \
+    --percent 100 \
+    --stage-end-percent 100 \
+    --stage-expected-seconds 0 \
+    --total-estimated-seconds "$TOTAL_WEIGHT" \
+    --message "3D preflight=$PREFLIGHT_DECISION; see 05_quality_checks/preflight.json"
+  echo "3D generation withheld. Review: $PREFLIGHT_DIR/preflight.json"
+  exit 0
+fi
+
+if [[ "$RUN_FAST_2D" == "1" ]]; then
+  start_stage "fast_2d" "Optional OpenCV 2D baseline" "$FAST_2D_WEIGHT"
+  completion_cmd=(
+    "$AMODAL3D_PYTHON" tools/accessibility_fast_2d_baseline.py
+    --image "$IMAGE"
+    --single-sample-id "$SAMPLE_ID"
+    --target-visible-mask "$MASK_OUTPUT/target_visible.png"
+    --target-amodal-mask "$MASK_OUTPUT/target_amodal.png"
+    --hidden-mask "$MASK_OUTPUT/hidden.png"
+    --obstacle-mask "$MASK_OUTPUT/obstacle.png"
+    --output-dir "$OUTPUT_DIR/03_fast_2d_baseline"
+    --mask-mode hidden
+    --opencv-mode pyramid
+    --overwrite
+  )
+  if [[ "$ALLOW_LARGE_2D" == "1" ]]; then
+    completion_cmd+=(--allow-large-mask)
+  fi
+  "${completion_cmd[@]}"
+  finish_stage "$FAST_2D_WEIGHT"
+fi
+
+if [[ "$RUN_GPU_2D" == "1" ]]; then
+  start_stage "gpu_2d" "GPU generative 2D completion and candidate selection" "$GPU_2D_WEIGHT"
+  "$AMODAL3D_PYTHON" tools/accessibility_2d_completion.py \
+    --image "$IMAGE" \
+    --mask "$MASK_OUTPUT/hidden.png" \
+    --obstacle-mask "$MASK_OUTPUT/obstacle_all_detected.png" \
+    --target-visible-mask "$MASK_OUTPUT/target_visible.png" \
+    --target-amodal-mask "$MASK_OUTPUT/target_amodal.png" \
+    --category "$CATEGORY" \
+    --output-dir "$OUTPUT_DIR/03_2d_completion" \
+    --model "$SD_MODEL" \
+    --device cuda
+  finish_stage "$GPU_2D_WEIGHT"
+  COMPLETION_STATUS="$("$AMODAL3D_PYTHON" -c 'import json,sys; print(json.load(open(sys.argv[1], encoding="utf-8")).get("status", "completed"))' "$OUTPUT_DIR/03_2d_completion/manifest.json")"
+  echo "2D completion quality status: $COMPLETION_STATUS"
+  case "$COMPLETION_STATUS" in
+    candidate_selected_for_review|skipped_empty_removal_mask)
+      ;;
+    *)
+      echo "The 2D candidate needs review and will not condition either 3D backend."
+      echo "Accessibility3D will still use the original RGB plus the strict three-value mask."
+      ;;
+  esac
+fi
+
+start_stage "geometry" "Depth and 3D geometry reconstruction" "$GEOMETRY_WEIGHT"
+REFERENCE_IMAGE=""
+if [[ "$RUN_GPU_2D" == "1" ]] \
+    && [[ "${COMPLETION_STATUS:-}" =~ ^(candidate_selected_for_review|skipped_empty_removal_mask)$ ]]; then
+  REFERENCE_IMAGE="$OUTPUT_DIR/03_2d_completion/completed_rgb_selected.png"
+fi
+pipeline_cmd=(
+  "$AMODAL3D_PYTHON" -m accessibilityamodal.pipeline
+  --image "$IMAGE"
+  --sample-id "$SAMPLE_ID"
+  --preset "$CATEGORY"
+  --target-visible-mask "$MASK_OUTPUT/target_visible.png"
+  --target-amodal-mask "$MASK_OUTPUT/target_amodal.png"
+  --obstacle-mask "$MASK_OUTPUT/obstacle.png"
+  --output-dir "$OUTPUT_DIR/04_3d_completion"
+)
+if [[ -n "$REFERENCE_IMAGE" ]]; then
+  pipeline_cmd+=(
+    --reference-image "$REFERENCE_IMAGE"
+    --completed-rgb "$REFERENCE_IMAGE"
+  )
+fi
+if [[ "$RUN_DEPTH" == "1" ]]; then
+  pipeline_cmd+=(
+    --estimate-depth
+    --depth-engine depth_anything_v2
+    --depth-device cuda
+    --depth-anything-repo "$DEPTH_REPO"
+    --depth-checkpoint "$DEPTH_CHECKPOINT"
+    --depth-encoder vitl
+    --metric-depth
+    --max-depth 20
+    --depth-fallback error
+  )
+fi
+"${pipeline_cmd[@]}"
+finish_stage "$GEOMETRY_WEIGHT"
+
+start_stage "surface_variants" "Auxiliary surface and canonical 3D views" "$VARIANTS_WEIGHT"
+variants_cmd=(
+  "$AMODAL3D_PYTHON" tools/accessibility_3d_variants.py
+  --geometry-dir "$OUTPUT_DIR/04_3d_completion/geometry"
+  --output-dir "$OUTPUT_DIR/04_3d_completion/geometry/presentation_models"
+  --sample-id "$SAMPLE_ID"
+  --category "$CATEGORY"
+  --frames 72
+  --duration-ms 140
+  --hidden-tint 0
+  --model-only
+)
+if [[ -n "$REFERENCE_IMAGE" ]]; then
+  variants_cmd+=(--texture-image "$REFERENCE_IMAGE")
+fi
+"${variants_cmd[@]}"
+finish_stage "$VARIANTS_WEIGHT"
+
+PRESENTATION_MESH="$OUTPUT_DIR/04_3d_completion/geometry/completed_mesh.ply"
+if [[ -f "$OUTPUT_DIR/04_3d_completion/geometry/presentation_models/02_canonical_stairs/02_canonical_stairs.ply" ]]; then
+  PRESENTATION_MESH="$OUTPUT_DIR/04_3d_completion/geometry/presentation_models/02_canonical_stairs/02_canonical_stairs.ply"
+elif [[ -f "$OUTPUT_DIR/04_3d_completion/geometry/presentation_models/02_continuous_support_surface/02_continuous_support_surface.ply" ]]; then
+  PRESENTATION_MESH="$OUTPUT_DIR/04_3d_completion/geometry/presentation_models/02_continuous_support_surface/02_continuous_support_surface.ply"
+fi
+
+start_stage "turntable" "Diagnostic category-geometry turntable" "$TURNTABLE_WEIGHT"
+"$AMODAL3D_PYTHON" "$GPU_TURNTABLE_TOOL" \
+  --ply "$PRESENTATION_MESH" \
+  --output-dir "$OUTPUT_DIR/04_3d_completion/turntable" \
+  --sample-id "$SAMPLE_ID" \
+  --category "$CATEGORY" \
+  --frames 96 \
+  --fps 24 \
+  --shader defaultUnlit \
+  --background 0.82,0.82,0.80,1 \
+  --orbit-mode front_arc \
+  --orbit-span 140 \
+  --multiview-yaws=-60,-30,0,30,60 \
+  --require-vertex-colors
+finish_stage "$TURNTABLE_WEIGHT"
+
+if [[ "$RUN_AMODAL3D_3D" == "1" ]]; then
+  start_stage "amodal3d" "Accessibility3D CUDA Gaussian rotation and dense mesh" "$AMODAL3D_WEIGHT"
+  amodal3d_cmd=(
+    "$AMODAL3D_PYTHON" tools/accessibility_3d_completion.py
+    --image "$IMAGE"
+    --conditioning-rgb original
+    --mask "$OUTPUT_DIR/04_3d_completion/amodal3d_three_value_mask.png"
+    --output-dir "$ACCESSIBILITY3D_DIR"
+    --model "$AMODAL3D_MODEL"
+  )
+  # Match the known-good 9527 run: the learned backend receives the original
+  # display-oriented RGB and the strict reviewed three-value condition mask.
+  # The separate 2D inpaint must never become foggy texture conditioning here.
+  if [[ "$RUN_AMODAL3D_GLB" == "1" ]]; then
+    amodal3d_cmd+=(--export-glb)
+  fi
+  AMODAL3D_TORCH_HOME="$AMODAL3D_TORCH_HOME" "${amodal3d_cmd[@]}"
+  finish_stage "$AMODAL3D_WEIGHT"
+
+  POST_3D_DECISION="$("$AMODAL3D_PYTHON" "$VERIFICATION_TOOL" \
+    --run-dir "$OUTPUT_DIR" \
+    --sample-id "$SAMPLE_ID" \
+    --category "$CATEGORY" \
+    --output "$PREFLIGHT_DIR/verification.json" \
+    --print-decision)"
+  echo "Generated 3D verification decision: $POST_3D_DECISION"
+
+  if [[ "$POST_3D_DECISION" == "accept" ]]; then
+    echo "Local 3D candidate passed the reconstruction-quality gate."
+    echo "Paper/GitHub packaging is intentionally withheld pending explicit human release approval for license/privacy and calibrated-geometry review."
+  else
+    echo "Learned 3D debug artifacts are withheld because generated 3D verification=$POST_3D_DECISION"
+  fi
+fi
+
+# Normalize persistent upstream manifests before the review bundle records
+# their byte hashes.  The EXIT trap runs the same sanitizer again as a final
+# privacy guard, but it is idempotent and must not invalidate review provenance.
+sanitize_output_metadata
+
+if [[ "$RUN_GPU_2D" == "1" ]]; then
+  PRIMARY_3D_ROLE="open_world_accessibility_surface"
+  PRIMARY_3D_GIF="$OUTPUT_DIR/04_3d_completion/turntable/turntable.gif"
+  PRIMARY_3D_MULTIVIEW="$OUTPUT_DIR/04_3d_completion/turntable/multiview.jpg"
+  PRIMARY_3D_MESH="$PRESENTATION_MESH"
+  if [[
+    "$RUN_AMODAL3D_3D" == "1" &&
+    "${POST_3D_DECISION:-}" == "accept" &&
+    -f "$ACCESSIBILITY3D_DIR/sample_gaussian.gif" &&
+    -f "$ACCESSIBILITY3D_DIR/multiview_contact_sheet.jpg" &&
+    -f "$ACCESSIBILITY3D_DIR/mesh.ply"
+  ]]; then
+    PRIMARY_3D_ROLE="learned_amodal3d_gaussian"
+    PRIMARY_3D_GIF="$ACCESSIBILITY3D_DIR/sample_gaussian.gif"
+    PRIMARY_3D_MULTIVIEW="$ACCESSIBILITY3D_DIR/multiview_contact_sheet.jpg"
+    PRIMARY_3D_MESH="$ACCESSIBILITY3D_DIR/mesh.ply"
+  fi
+  review_cmd=(
+    "$AMODAL3D_PYTHON" "$REVIEW_BUNDLE_TOOL"
+    --source "$IMAGE"
+    --completion-2d "$OUTPUT_DIR/03_2d_completion/completed_rgb_selected.png"
+    --turntable-gif "$PRIMARY_3D_GIF"
+    --multiview "$PRIMARY_3D_MULTIVIEW"
+    --mesh "$PRIMARY_3D_MESH"
+    --primary-3d-role "$PRIMARY_3D_ROLE"
+    --completion-manifest "$OUTPUT_DIR/03_2d_completion/manifest.json"
+    --geometry-manifest "$OUTPUT_DIR/04_3d_completion/geometry/geometry_manifest.json"
+    --category "$CATEGORY"
+    --sample-id "$SAMPLE_ID"
+    --output-dir "$OUTPUT_DIR"
+  )
+  if [[ -f "$PREFLIGHT_DIR/verification.json" ]]; then
+    review_cmd+=(
+      --verification-manifest "$PREFLIGHT_DIR/verification.json"
+    )
+  fi
+  "${review_cmd[@]}"
+fi
+
+FINAL_STAGE_LABEL="All requested local outputs completed"
+if [[ "$RUN_AMODAL3D_3D" == "1" ]]; then
+  FINAL_STAGE_LABEL="Local 3D outputs completed; public release withheld pending human approval"
+  if [[ "$POST_3D_DECISION" != "accept" ]]; then
+    FINAL_STAGE_LABEL="3D debug artifacts generated but withheld after verification"
+  fi
+fi
+"$AMODAL3D_PYTHON" "$PROGRESS_WRITER" \
+  --path "$PROGRESS_FILE" \
+  --status completed \
+  --stage-key completed \
+  --stage-label "$FINAL_STAGE_LABEL" \
+  --percent 100 \
+  --stage-end-percent 100 \
+  --stage-expected-seconds 0 \
+  --total-estimated-seconds "$TOTAL_WEIGHT"
+
+echo "Completed. Review these first:"
+if [[ "$RUN_GPU_2D" == "1" ]]; then
+  echo "  $OUTPUT_DIR/00_quick_review/overview.jpg"
+  echo "  $OUTPUT_DIR/00_quick_review/03_3d_turntable.gif"
+fi
+echo "  $MASK_OUTPUT/mask_overlay.png"
+if [[ "$RUN_GPU_2D" == "1" ]]; then
+  echo "  $OUTPUT_DIR/03_2d_completion/completed_rgb_selected.png"
+  echo "  $OUTPUT_DIR/03_2d_completion/candidate_comparison.jpg"
+fi
+if [[ "$RUN_FAST_2D" == "1" ]]; then
+  echo "  $OUTPUT_DIR/03_fast_2d_baseline/$SAMPLE_ID/contact_sheet.jpg"
+fi
+echo "  $OUTPUT_DIR/04_3d_completion/geometry/completed_region_overlay.png"
+echo "  $OUTPUT_DIR/04_3d_completion/geometry/completed_mesh.ply"
+echo "  $OUTPUT_DIR/04_3d_completion/geometry/presentation_models/manifest.json"
+echo "  diagnostic geometry mesh: $PRESENTATION_MESH"
+if [[ "$RUN_AMODAL3D_3D" == "1" ]]; then
+  echo "  $OUTPUT_DIR/05_quality_checks/verification.json"
+  echo "  source-colored CUDA rotation: $ACCESSIBILITY3D_DIR/sample_gaussian.gif"
+  echo "  CUDA mesh-normal diagnostic: $ACCESSIBILITY3D_DIR/sample_mesh.gif"
+  echo "  primary multiview: $ACCESSIBILITY3D_DIR/multiview_contact_sheet.jpg"
+  echo "  dense triangle mesh: $ACCESSIBILITY3D_DIR/mesh.ply"
+  if [[ "$RUN_AMODAL3D_GLB" == "1" ]]; then
+    echo "  dense GLB mesh: $ACCESSIBILITY3D_DIR/mesh.glb"
+  fi
+fi

tools/accessibility_2d_completion.py

@@ -0,0 +1,604 @@
+#!/usr/bin/env python3
+"""GPU generative 2D completion for accessibility-scene occlusions.
+
+The module is a project-owned orchestration layer.  It uses a locally supplied
+Diffusers inpainting checkpoint as a backend, preserves all pixels outside the
+reviewed completion mask, ranks several candidates using staircase-oriented
+image evidence, and publishes one deterministic selected result.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+import torch
+from PIL import Image, ImageDraw, ImageFilter, ImageOps
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from accessibilityamodal.visual_completion import (  # noqa: E402
+    NEGATIVE_PROMPT,
+    PROMPTS,
+    apply_selection_clutter_penalty,
+    build_completion_envelope,
+    build_visual_removal_mask,
+    candidate_clutter_metrics,
+    candidate_quality,
+    derive_hidden_mask,
+    mask_statistics,
+    select_candidate,
+)
+
+
+def resolve_path(value: str | Path) -> Path:
+    path = Path(value).expanduser()
+    return path.resolve() if path.is_absolute() else (PROJECT_ROOT / path).resolve()
+
+
+def load_rgb(path: Path) -> Image.Image:
+    """Read RGB in the display orientation used to generate the proposal masks."""
+    return ImageOps.exif_transpose(Image.open(path)).convert("RGB")
+
+
+def load_binary_mask(path: Path, size: tuple[int, int]) -> Image.Image:
+    mask = ImageOps.exif_transpose(Image.open(path)).convert("L")
+    if mask.size != size:
+        raise ValueError(
+            f"Mask/RGB raster mismatch for {path}: mask={mask.size}, rgb={size}. "
+            "Refusing to resize because this can hide EXIF-orientation misalignment."
+        )
+    return Image.fromarray((np.asarray(mask) > 127).astype(np.uint8) * 255, mode="L")
+
+
+def portable_input_reference(path: Path) -> dict[str, str]:
+    """Describe an input without embedding a machine-specific absolute path."""
+
+    try:
+        return {
+            "base": "project_root",
+            "path": path.resolve().relative_to(PROJECT_ROOT).as_posix(),
+        }
+    except ValueError:
+        return {"base": "external_input", "path": path.name}
+
+
+def load_completion_masks(
+    *,
+    size: tuple[int, int],
+    hidden_path: Path | None,
+    obstacle_path: Path | None,
+    target_amodal_path: Path | None,
+    target_visible_path: Path | None,
+) -> tuple[Image.Image, Image.Image, dict[str, Any]]:
+    """Load geometry hidden and build the separate visual removal mask."""
+
+    if bool(target_amodal_path) != bool(target_visible_path):
+        raise ValueError(
+            "--target-amodal-mask and --target-visible-mask must be provided together"
+        )
+    if hidden_path is None and target_amodal_path is None:
+        raise ValueError(
+            "Provide --mask, or provide both --target-amodal-mask and --target-visible-mask"
+        )
+
+    hidden_from_file = (
+        np.asarray(load_binary_mask(hidden_path, size)) > 127
+        if hidden_path is not None
+        else None
+    )
+    target_amodal = (
+        np.asarray(load_binary_mask(target_amodal_path, size)) > 127
+        if target_amodal_path is not None
+        else None
+    )
+    target_visible = (
+        np.asarray(load_binary_mask(target_visible_path, size)) > 127
+        if target_visible_path is not None
+        else None
+    )
+    hidden_from_targets = (
+        derive_hidden_mask(target_amodal, target_visible)
+        if target_amodal is not None and target_visible is not None
+        else None
+    )
+    if (
+        hidden_from_file is not None
+        and hidden_from_targets is not None
+        and not np.array_equal(hidden_from_file, hidden_from_targets)
+    ):
+        mismatch = int(np.count_nonzero(hidden_from_file ^ hidden_from_targets))
+        raise ValueError(
+            "--mask disagrees with target_amodal AND NOT target_visible "
+            f"at {mismatch} pixels"
+        )
+
+    geometry_hidden = (
+        hidden_from_targets if hidden_from_targets is not None else hidden_from_file
+    )
+    assert geometry_hidden is not None
+    obstacle = (
+        np.asarray(load_binary_mask(obstacle_path, size)) > 127
+        if obstacle_path is not None
+        else None
+    )
+    visual_removal, policy_stats = build_visual_removal_mask(
+        geometry_hidden,
+        obstacle,
+    )
+    report: dict[str, Any] = {
+        "hidden_source": (
+            "target_amodal_minus_target_visible"
+            if hidden_from_targets is not None
+            else "legacy_hidden_mask"
+        ),
+        "geometry_hidden": policy_stats["geometry_hidden"],
+        "obstacle_input": {
+            "provided": obstacle is not None,
+            **policy_stats["obstacle_input"],
+        },
+        "obstacle_retained": policy_stats["obstacle_retained"],
+        "visual_removal": policy_stats["visual_removal"],
+        "visual_removal_policy": policy_stats,
+        "target_amodal": (
+            {"provided": True, **mask_statistics(target_amodal)}
+            if target_amodal is not None
+            else {"provided": False}
+        ),
+        "target_visible": (
+            {"provided": True, **mask_statistics(target_visible)}
+            if target_visible is not None
+            else {"provided": False}
+        ),
+    }
+    return (
+        Image.fromarray(geometry_hidden.astype(np.uint8) * 255, mode="L"),
+        Image.fromarray(visual_removal.astype(np.uint8) * 255, mode="L"),
+        report,
+    )
+
+
+def dilate(mask: Image.Image, radius: int) -> Image.Image:
+    if radius <= 0:
+        return mask
+    array = np.asarray(mask) > 127
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (radius * 2 + 1, radius * 2 + 1))
+    return Image.fromarray(cv2.dilate(array.astype(np.uint8), kernel) * 255, mode="L")
+
+
+def crop_around_mask(mask: Image.Image, padding: int) -> tuple[int, int, int, int]:
+    binary = np.asarray(mask) > 127
+    ys, xs = np.where(binary)
+    if not len(xs):
+        raise ValueError("The 2D completion mask is empty")
+    width, height = mask.size
+    x1, x2 = int(xs.min()), int(xs.max()) + 1
+    y1, y2 = int(ys.min()), int(ys.max()) + 1
+    x1, y1 = max(0, x1 - padding), max(0, y1 - padding)
+    x2, y2 = min(width, x2 + padding), min(height, y2 + padding)
+
+    # A near-square crop gives the diffusion model enough visible context on
+    # both sides of a narrow structural occluder.
+    side = max(x2 - x1, y2 - y1)
+    cx, cy = (x1 + x2) / 2.0, (y1 + y2) / 2.0
+    x1, y1 = int(round(cx - side / 2.0)), int(round(cy - side / 2.0))
+    x2, y2 = x1 + side, y1 + side
+    if x1 < 0:
+        x2, x1 = x2 - x1, 0
+    if y1 < 0:
+        y2, y1 = y2 - y1, 0
+    if x2 > width:
+        x1, x2 = max(0, x1 - (x2 - width)), width
+    if y2 > height:
+        y1, y2 = max(0, y1 - (y2 - height)), height
+    return x1, y1, x2, y2
+
+
+def model_size(size: tuple[int, int], maximum: int) -> tuple[int, int]:
+    width, height = size
+    scale = min(maximum / max(width, height), 1.0)
+    return (
+        max(64, int(round(width * scale / 8.0)) * 8),
+        max(64, int(round(height * scale / 8.0)) * 8),
+    )
+
+
+def composite_generated_crop(
+    source: Image.Image,
+    generated: Image.Image,
+    mask_crop: Image.Image,
+    box: tuple[int, int, int, int],
+    feather_radius: float,
+    preserve_crop: Image.Image | None = None,
+) -> Image.Image:
+    x1, y1, x2, y2 = box
+    crop_size = (x2 - x1, y2 - y1)
+    generated = generated.convert("RGB").resize(crop_size, Image.Resampling.LANCZOS)
+    alpha = mask_crop.resize(crop_size, Image.Resampling.NEAREST)
+    if feather_radius > 0:
+        alpha = alpha.filter(ImageFilter.GaussianBlur(feather_radius))
+    if preserve_crop is not None:
+        preserve = (
+            np.asarray(
+                preserve_crop.resize(crop_size, Image.Resampling.NEAREST).convert("L")
+            )
+            > 127
+        )
+        alpha_array = np.asarray(alpha).copy()
+        alpha_array[preserve] = 0
+        alpha = Image.fromarray(alpha_array, mode="L")
+    result = source.copy()
+    result.paste(generated, (x1, y1), alpha)
+    return result
+
+
+def labelled_panel(image: Image.Image, label: str, size: tuple[int, int]) -> Image.Image:
+    body = ImageOps.contain(image.convert("RGB"), (size[0], size[1] - 34))
+    panel = Image.new("RGB", size, "white")
+    ImageDraw.Draw(panel).text((9, 10), label, fill=(20, 20, 20))
+    panel.paste(body, ((size[0] - body.width) // 2, 34 + (size[1] - 34 - body.height) // 2))
+    return panel
+
+
+def write_candidate_grid(
+    path: Path,
+    source: Image.Image,
+    mask: Image.Image,
+    candidates: list[dict[str, Any]],
+) -> None:
+    overlay = source.copy()
+    overlay.paste(Image.new("RGB", source.size, (255, 45, 30)), mask=mask)
+    overlay = Image.blend(source, overlay, 0.52)
+    panel_size = (400, 560)
+    items = [labelled_panel(source, "source", panel_size), labelled_panel(overlay, "completion mask", panel_size)]
+    for row in candidates:
+        quality = row["quality"]
+        label = (
+            f"candidate {row['index']} | score {quality['score']:.3f} "
+            f"| gate {quality.get('gate_score', quality['score']):.3f}"
+        )
+        if "selection_score" in quality:
+            label += f" | select {quality['selection_score']:.3f}"
+        if quality.get("quality_flags"):
+            label += " | " + ",".join(quality["quality_flags"])
+        if row.get("selected"):
+            label += " | REVIEW PICK"
+        items.append(labelled_panel(Image.open(row["completed_rgb"]), label, panel_size))
+    columns = 3
+    rows = math.ceil(len(items) / columns)
+    sheet = Image.new("RGB", (columns * panel_size[0], rows * panel_size[1]), (240, 240, 240))
+    for index, item in enumerate(items):
+        sheet.paste(item, ((index % columns) * panel_size[0], (index // columns) * panel_size[1]))
+    sheet.save(path, quality=94, subsampling=0)
+
+
+def load_backend(model: Path, device: str):
+    from diffusers import StableDiffusionInpaintPipeline
+
+    dtype = torch.float16 if device.startswith("cuda") else torch.float32
+    pipeline = StableDiffusionInpaintPipeline.from_pretrained(
+        str(model),
+        torch_dtype=dtype,
+        variant="fp16" if dtype == torch.float16 else None,
+        safety_checker=None,
+        requires_safety_checker=False,
+        local_files_only=True,
+    )
+    pipeline = pipeline.to(device)
+    pipeline.set_progress_bar_config(desc="Accessibility GPU 2D", leave=False)
+    return pipeline
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--image", required=True)
+    parser.add_argument(
+        "--mask",
+        default=None,
+        help=(
+            "Legacy reviewed hidden mask. Optional when both target masks are supplied; "
+            "this geometry mask is never expanded to whole obstacle instances."
+        ),
+    )
+    parser.add_argument(
+        "--obstacle-mask",
+        default=None,
+        help=(
+            "Detected obstacle mask. Visual removal keeps only complete connected "
+            "components intersecting hidden; nearby non-occluding people remain."
+        ),
+    )
+    parser.add_argument("--target-amodal-mask", default=None)
+    parser.add_argument("--target-visible-mask", default=None)
+    parser.add_argument("--category", choices=tuple(PROMPTS), required=True)
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--model", default="weights/stable-diffusion-inpainting")
+    parser.add_argument("--prompt", default=None)
+    parser.add_argument("--negative-prompt", default=NEGATIVE_PROMPT)
+    parser.add_argument("--seed", type=int, default=9527)
+    parser.add_argument("--steps", type=int, default=45)
+    parser.add_argument("--guidance-scale", type=float, default=6.5)
+    parser.add_argument("--num-candidates", type=int, default=4)
+    parser.add_argument("--crop-padding", type=int, default=220)
+    parser.add_argument("--resolution", type=int, default=768)
+    parser.add_argument("--mask-dilate", type=int, default=8)
+    parser.add_argument("--feather-radius", type=float, default=3.0)
+    parser.add_argument("--device", default="cuda")
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    if args.num_candidates < 1 or args.steps < 1:
+        raise ValueError("num-candidates and steps must be positive")
+    image_path = resolve_path(args.image)
+    mask_path = resolve_path(args.mask) if args.mask else None
+    obstacle_path = resolve_path(args.obstacle_mask) if args.obstacle_mask else None
+    target_amodal_path = (
+        resolve_path(args.target_amodal_mask) if args.target_amodal_mask else None
+    )
+    target_visible_path = (
+        resolve_path(args.target_visible_mask) if args.target_visible_mask else None
+    )
+    model_path = resolve_path(args.model)
+    output_dir = resolve_path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    source = load_rgb(image_path)
+    geometry_hidden_mask, visual_removal_mask, mask_report = load_completion_masks(
+        size=source.size,
+        hidden_path=mask_path,
+        obstacle_path=obstacle_path,
+        target_amodal_path=target_amodal_path,
+        target_visible_path=target_visible_path,
+    )
+    if obstacle_path is not None:
+        obstacle_array = np.asarray(load_binary_mask(obstacle_path, source.size)) > 127
+        protected_non_occluding = obstacle_array & ~(
+            np.asarray(visual_removal_mask) > 127
+        )
+    else:
+        protected_non_occluding = np.zeros(
+            (source.height, source.width),
+            dtype=bool,
+        )
+        obstacle_array = None
+    completion_envelope, envelope_report = build_completion_envelope(
+        np.asarray(visual_removal_mask) > 127,
+        obstacle_array,
+    )
+    completion_envelope_mask = Image.fromarray(
+        completion_envelope.astype(np.uint8) * 255,
+        mode="L",
+    )
+    target_amodal_array = (
+        np.asarray(load_binary_mask(target_amodal_path, source.size)) > 127
+        if target_amodal_path is not None
+        else None
+    )
+    generation_mask = dilate(completion_envelope_mask, args.mask_dilate)
+    # Dilation and feathering must not nibble into a nearby person/object that
+    # the component policy intentionally excluded.
+    generation_array = (np.asarray(generation_mask) > 127) & ~protected_non_occluding
+    generation_mask = Image.fromarray(
+        generation_array.astype(np.uint8) * 255,
+        mode="L",
+    )
+    protected_non_occluding_mask = Image.fromarray(
+        protected_non_occluding.astype(np.uint8) * 255,
+        mode="L",
+    )
+    mask_report["generation_after_dilation"] = mask_statistics(
+        generation_array
+    )
+    mask_report["completion_envelope"] = envelope_report
+    mask_report["protected_non_occluding_obstacle"] = mask_statistics(
+        protected_non_occluding
+    )
+    mask_report["generation_mask_dilate_radius"] = args.mask_dilate
+    geometry_hidden_mask.save(output_dir / "geometry_hidden_mask.png")
+    # Preserve the legacy review filename for downstream readers.
+    geometry_hidden_mask.save(output_dir / "reviewed_hidden_mask.png")
+    visual_removal_mask.save(output_dir / "visual_removal_mask.png")
+    completion_envelope_mask.save(output_dir / "completion_envelope_mask.png")
+    generation_mask.save(output_dir / "generation_mask.png")
+    protected_non_occluding_mask.save(
+        output_dir / "protected_non_occluding_obstacle_mask.png"
+    )
+
+    input_references = {
+        "image": portable_input_reference(image_path),
+        "legacy_hidden": (
+            portable_input_reference(mask_path) if mask_path is not None else None
+        ),
+        "obstacle": (
+            portable_input_reference(obstacle_path) if obstacle_path is not None else None
+        ),
+        "target_amodal": (
+            portable_input_reference(target_amodal_path)
+            if target_amodal_path is not None
+            else None
+        ),
+        "target_visible": (
+            portable_input_reference(target_visible_path)
+            if target_visible_path is not None
+            else None
+        ),
+    }
+    if not np.any(np.asarray(generation_mask) > 127):
+        selected = output_dir / "completed_rgb_selected.png"
+        source.save(selected)
+        manifest = {
+            "schema_version": "accessibilityamodal_visual_completion_v1",
+            "status": "skipped_empty_removal_mask",
+            "human_review_required": True,
+            "automatic_passability_claim": False,
+            "inputs": input_references,
+            "mask_statistics": mask_report,
+            "files": {
+                "geometry_hidden_mask": "geometry_hidden_mask.png",
+                "visual_removal_mask": "visual_removal_mask.png",
+                "completion_envelope_mask": "completion_envelope_mask.png",
+                "generation_mask": "generation_mask.png",
+                "protected_non_occluding_obstacle_mask": (
+                    "protected_non_occluding_obstacle_mask.png"
+                ),
+                "selected_completed_rgb": selected.name,
+            },
+            "selected_completed_rgb": selected.name,
+            "warning": (
+                "Visual completion outputs are review candidates, not ground truth "
+                "or evidence that a route is passable."
+            ),
+        }
+        (output_dir / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+        return 0
+
+    box = crop_around_mask(generation_mask, args.crop_padding)
+    source_crop = source.crop(box)
+    mask_crop = generation_mask.crop(box)
+    preserve_crop = protected_non_occluding_mask.crop(box)
+    inference_size = model_size(source_crop.size, args.resolution)
+    model_image = source_crop.resize(inference_size, Image.Resampling.LANCZOS)
+    model_mask = mask_crop.resize(inference_size, Image.Resampling.NEAREST)
+    device = args.device if not args.device.startswith("cuda") or torch.cuda.is_available() else "cpu"
+    prompt = args.prompt or PROMPTS[args.category]
+    pipeline = load_backend(model_path, device)
+
+    candidates: list[dict[str, Any]] = []
+    for index in range(args.num_candidates):
+        seed = args.seed + index * 1009
+        generator = torch.Generator(device=device).manual_seed(seed)
+        generated = pipeline(
+            prompt=prompt,
+            negative_prompt=args.negative_prompt,
+            image=model_image,
+            mask_image=model_mask,
+            num_inference_steps=args.steps,
+            guidance_scale=args.guidance_scale,
+            generator=generator,
+        ).images[0]
+        completed = composite_generated_crop(
+            source,
+            generated,
+            mask_crop,
+            box,
+            args.feather_radius,
+            preserve_crop=preserve_crop,
+        )
+        completed_path = output_dir / f"completed_rgb_candidate_{index:02d}.png"
+        crop_path = output_dir / f"generated_crop_candidate_{index:02d}.png"
+        completed.save(completed_path)
+        generated.save(crop_path)
+        quality = candidate_quality(
+            completed,
+            geometry_hidden_mask,
+            args.category,
+        )
+        quality["clutter_metrics"] = candidate_clutter_metrics(
+            completed,
+            source,
+            completion_envelope,
+            target_amodal_array,
+        )
+        candidates.append(
+            {
+                "index": index,
+                "seed": seed,
+                "completed_rgb": str(completed_path),
+                "generated_crop": str(crop_path),
+                "quality": quality,
+            }
+        )
+
+    apply_selection_clutter_penalty(candidates)
+    selected_row, status = select_candidate(candidates)
+    selected_row["selected"] = True
+    selected_path = output_dir / "completed_rgb_selected.png"
+    shutil.copy2(selected_row["completed_rgb"], selected_path)
+    source_crop.save(output_dir / "source_context_crop.png")
+    write_candidate_grid(output_dir / "candidate_comparison.jpg", source, generation_mask, candidates)
+
+    manifest_candidates = []
+    for row in candidates:
+        portable_row = dict(row)
+        portable_row["completed_rgb"] = Path(row["completed_rgb"]).name
+        portable_row["generated_crop"] = Path(row["generated_crop"]).name
+        manifest_candidates.append(portable_row)
+    manifest = {
+        "schema_version": "accessibilityamodal_visual_completion_v1",
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "status": status,
+        "human_review_required": True,
+        "automatic_passability_claim": False,
+        "pipeline": "AccessibilityAmodal GPU 2D Visual Completion",
+        "backend": "Diffusers StableDiffusionInpaintPipeline",
+        "inputs": input_references,
+        "mask_statistics": mask_report,
+        "quality_evaluation_mask": "geometry_hidden_mask.png",
+        "category": args.category,
+        "model": portable_input_reference(model_path),
+        "prompt": prompt,
+        "negative_prompt": args.negative_prompt,
+        "device": device,
+        "steps": args.steps,
+        "guidance_scale": args.guidance_scale,
+        "crop_box": box,
+        "inference_size": inference_size,
+        "mask_dilate": args.mask_dilate,
+        "feather_radius": args.feather_radius,
+        "selected_index": selected_row["index"],
+        "selection_score_policy": (
+            "absolute_hidden_surface_quality_minus_up_to_0.15_"
+            "cohort_relative_outside_target_clutter_rank"
+        ),
+        "selected_completed_rgb": selected_path.name,
+        "candidate_comparison": "candidate_comparison.jpg",
+        "files": {
+            "geometry_hidden_mask": "geometry_hidden_mask.png",
+            "visual_removal_mask": "visual_removal_mask.png",
+            "completion_envelope_mask": "completion_envelope_mask.png",
+            "generation_mask": "generation_mask.png",
+            "protected_non_occluding_obstacle_mask": (
+                "protected_non_occluding_obstacle_mask.png"
+            ),
+            "source_context_crop": "source_context_crop.png",
+            "selected_completed_rgb": selected_path.name,
+            "candidate_comparison": "candidate_comparison.jpg",
+        },
+        "candidates": manifest_candidates,
+        "warning": (
+            "Generative 2D outputs are visual review candidates, not ground truth "
+            "or evidence that a route is passable."
+        ),
+    }
+    (output_dir / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    if status == "withheld_needs_review":
+        print(
+            f"All candidates carry quality risks; retained candidate "
+            f"{selected_row['index']} for review and withheld automatic acceptance."
+        )
+    else:
+        print(
+            f"Selected visual candidate {selected_row['index']} by gate score "
+            f"{selected_row['quality']['gate_score']:.4f}; human review remains required."
+        )
+    print(f"Wrote GPU 2D review candidate to {selected_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/accessibility_3d_completion.py

@@ -0,0 +1,1150 @@
+#!/usr/bin/env python3
+"""AccessibilityAmodal adapter for the licensed Amodal3R visual 3D backend.
+
+This file contains project-owned input/output orchestration. The model package
+imported as ``amodal3d`` remains third-party code under its upstream license.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import importlib
+import importlib.util
+import json
+import math
+import os
+import shutil
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import cv2
+import imageio
+import numpy as np
+import trimesh
+from PIL import Image, ImageOps
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT))
+
+os.environ["ATTN_BACKEND"] = "xformers"
+os.environ["SPARSE_ATTN_BACKEND"] = "xformers"
+os.environ["XFORMERS_DISABLED"] = "1"
+os.environ["SPCONV_ALGO"] = "native"
+os.environ["TORCH_HOME"] = os.environ.get(
+    "AMODAL3D_TORCH_HOME", str(PROJECT_ROOT / "weights" / "torch")
+)
+
+VISIBLE_VALUE = 188
+OCCLUDED_VALUE = 0
+BACKGROUND_VALUE = 255
+THREE_VALUE_MASK_VALUES = (OCCLUDED_VALUE, VISIBLE_VALUE, BACKGROUND_VALUE)
+ACCEPTED_COMPLETION_STATUSES = frozenset({"candidate_selected_for_review"})
+
+
+def resolve_path(value: str | Path) -> Path:
+    path = Path(value).expanduser()
+    return path.resolve() if path.is_absolute() else (PROJECT_ROOT / path).resolve()
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def portable_file_record(path: Path) -> dict[str, Any]:
+    """Record an input without embedding a workstation-specific absolute path."""
+
+    resolved = path.resolve()
+    try:
+        base = "project_root"
+        relative = resolved.relative_to(PROJECT_ROOT).as_posix()
+    except ValueError:
+        base = "external_input"
+        relative = resolved.name
+    return {
+        "base": base,
+        "path": relative,
+        "sha256": sha256_file(resolved),
+        "bytes": resolved.stat().st_size,
+    }
+
+
+def _declared_selected_path_matches(
+    declared: str,
+    *,
+    completion_manifest: Path,
+    completed_image: Path,
+) -> bool:
+    path = Path(declared).expanduser()
+    if path.is_absolute():
+        return path.resolve() == completed_image.resolve()
+    candidates = (
+        completion_manifest.parent / path,
+        completion_manifest.parent.parent / path,
+    )
+    return any(candidate.resolve() == completed_image.resolve() for candidate in candidates)
+
+
+def _resolve_completion_manifest_artifact(
+    declared: str,
+    *,
+    completion_manifest: Path,
+) -> Path:
+    path = Path(declared).expanduser()
+    candidates = (
+        (path,) if path.is_absolute() else (
+            completion_manifest.parent / path,
+            completion_manifest.parent.parent / path,
+        )
+    )
+    existing = [candidate.resolve() for candidate in candidates if candidate.is_file()]
+    if not existing:
+        raise FileNotFoundError(
+            f"Completion manifest artifact does not exist: {declared}"
+        )
+    return existing[0]
+
+
+def validate_completed_rgb_texture_preservation(
+    *,
+    original: Path,
+    completed: Path,
+    completion_manifest: Path,
+    payload: dict[str, Any],
+) -> dict[str, Any]:
+    """Prove that a 2D completion preserves source RGB outside its edit mask."""
+
+    files = payload.get("files")
+    file_records = files if isinstance(files, dict) else {}
+    declared_mask = (
+        payload.get("appearance_generation_mask")
+        or file_records.get("generation_mask")
+    )
+    if not isinstance(declared_mask, str):
+        raise ValueError(
+            "Accepted completed RGB manifest must declare its exact generation "
+            "mask as appearance_generation_mask or files.generation_mask"
+        )
+    generation_mask = _resolve_completion_manifest_artifact(
+        declared_mask,
+        completion_manifest=completion_manifest,
+    )
+    with (
+        Image.open(original) as original_source,
+        Image.open(completed) as completed_source,
+        Image.open(generation_mask) as mask_source,
+    ):
+        original_image = ImageOps.exif_transpose(original_source).convert("RGB")
+        completed_image = ImageOps.exif_transpose(completed_source).convert("RGB")
+        mask_image = ImageOps.exif_transpose(mask_source).convert("L")
+    if original_image.size != completed_image.size:
+        raise ValueError(
+            "Accepted completed RGB must use the same display raster as the original"
+        )
+    if mask_image.size != original_image.size:
+        raise ValueError(
+            "Completion generation mask must align exactly with original/completed RGB"
+        )
+
+    original_array = np.asarray(original_image, dtype=np.uint8)
+    completed_array = np.asarray(completed_image, dtype=np.uint8)
+    generation = np.asarray(mask_image, dtype=np.uint8) > 127
+    feather_radius = float(payload.get("feather_radius") or 0.0)
+    if not math.isfinite(feather_radius) or feather_radius < 0:
+        raise ValueError("Completion manifest feather_radius must be non-negative")
+    allowed = generation.astype(np.uint8)
+    feather_support_radius = int(math.ceil(3.0 * feather_radius))
+    if feather_support_radius > 0:
+        kernel = cv2.getStructuringElement(
+            cv2.MORPH_ELLIPSE,
+            (
+                feather_support_radius * 2 + 1,
+                feather_support_radius * 2 + 1,
+            ),
+        )
+        allowed = cv2.dilate(allowed, kernel)
+    allowed = allowed > 0
+    changed = np.any(original_array != completed_array, axis=2)
+    changed_outside = changed & ~allowed
+    changed_inside = changed & allowed
+    changed_outside_count = int(changed_outside.sum())
+    if changed_outside_count:
+        raise ValueError(
+            "Completed RGB changes source texture outside its declared generation "
+            f"mask/feather support at {changed_outside_count} pixels"
+        )
+    changed_inside_count = int(changed_inside.sum())
+    if changed_inside_count == 0:
+        raise ValueError(
+            "Completed RGB does not change any pixel inside its declared edit region"
+        )
+    outside_count = int((~allowed).sum())
+    return {
+        "validated": True,
+        "generation_mask": portable_file_record(generation_mask),
+        "feather_radius": feather_radius,
+        "feather_support_radius_pixels": feather_support_radius,
+        "allowed_edit_pixel_count": int(allowed.sum()),
+        "changed_inside_allowed_region_pixel_count": changed_inside_count,
+        "changed_outside_allowed_region_pixel_count": 0,
+        "source_rgb_identity_outside_allowed_region": True,
+        "source_rgb_identity_outside_allowed_region_ratio": (
+            1.0 if outside_count else None
+        ),
+    }
+
+
+def select_backend_rgb(args: argparse.Namespace) -> tuple[Path, dict[str, Any]]:
+    """Choose the explicitly requested RGB conditioning source.
+
+    The original image remains the canonical geometry/provenance source.
+    Completion arguments cannot replace it unless ``--conditioning-rgb
+    completed`` is explicit and the completion manifest passes the quality
+    gate.
+    """
+
+    original = resolve_path(args.image)
+    if not original.is_file():
+        raise FileNotFoundError(original)
+    conditioning_rgb = str(getattr(args, "conditioning_rgb", "original"))
+    completed_value = getattr(args, "completed_image", None)
+    manifest_value = getattr(args, "completion_manifest", None)
+    completion_inputs_supplied = bool(completed_value or manifest_value)
+
+    if conditioning_rgb == "original":
+        original_record = portable_file_record(original)
+        return original, {
+            "conditioning_rgb_mode": "original",
+            "backend_rgb_role": "original_rgb_no_accepted_2d_completion",
+            "backend_rgb": original_record,
+            "original_rgb": original_record,
+            "selected_completion_rgb": None,
+            "completion_manifest": None,
+            "completion_status": None,
+            "quality_gate_accepted": False,
+            "completion_inputs_supplied": completion_inputs_supplied,
+            "completion_inputs_ignored": completion_inputs_supplied,
+            "original_vs_completed": {
+                "same_raster_size": None,
+                "same_sha256": None,
+            },
+        }
+
+    if conditioning_rgb != "completed":
+        raise ValueError(
+            "--conditioning-rgb must be either 'original' or 'completed'"
+        )
+    if not completed_value or not manifest_value:
+        raise ValueError(
+            "--conditioning-rgb completed requires both --completed-image and "
+            "--completion-manifest"
+        )
+
+    completed = resolve_path(completed_value)
+    completion_manifest = resolve_path(manifest_value)
+    if not completed.is_file():
+        raise FileNotFoundError(completed)
+    if not completion_manifest.is_file():
+        raise FileNotFoundError(completion_manifest)
+    payload = json.loads(completion_manifest.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError("Completion manifest must contain a JSON object")
+    status = str(payload.get("status") or "")
+    if status not in ACCEPTED_COMPLETION_STATUSES:
+        raise ValueError(
+            "Refusing completed RGB for learned visual 3D because completion "
+            f"status is not accepted: {status or '<missing>'}"
+        )
+    files = payload.get("files")
+    declared_from_files = (
+        files.get("selected_completed_rgb") if isinstance(files, dict) else None
+    )
+    declared = payload.get("selected_completed_rgb") or declared_from_files
+    if not isinstance(declared, str) or not _declared_selected_path_matches(
+        declared,
+        completion_manifest=completion_manifest,
+        completed_image=completed,
+    ):
+        raise ValueError(
+            "Completion manifest does not identify --completed-image as its "
+            "selected completion"
+        )
+
+    texture_preservation = validate_completed_rgb_texture_preservation(
+        original=original,
+        completed=completed,
+        completion_manifest=completion_manifest,
+        payload=payload,
+    )
+    original_record = portable_file_record(original)
+    completed_record = portable_file_record(completed)
+    return completed, {
+        "conditioning_rgb_mode": "completed",
+        "backend_rgb_role": (
+            "quality_gate_accepted_obstacle_removed_rgb_preserving_original_texture"
+        ),
+        "backend_rgb": completed_record,
+        "original_rgb": original_record,
+        "selected_completion_rgb": completed_record,
+        "completion_manifest": portable_file_record(completion_manifest),
+        "completion_status": status,
+        "completion_manifest_selected_rgb": Path(declared).name,
+        "quality_gate_accepted": True,
+        "completion_inputs_supplied": True,
+        "completion_inputs_ignored": False,
+        "original_vs_completed": {
+            "same_raster_size": True,
+            "same_sha256": original_record["sha256"] == completed_record["sha256"],
+        },
+        "original_texture_preservation": texture_preservation,
+    }
+
+
+def load_backend_runtime():
+    """Import the licensed third-party runtime only for an actual GPU run."""
+
+    from amodal3d.pipelines import Amodal3RImageTo3DPipeline
+    from amodal3d.utils import render_utils
+
+    return Amodal3RImageTo3DPipeline, render_utils
+
+
+def extract_glb(gs, mesh, mesh_simplify=0.95, texture_size=1024, export_path="output.glb"):
+    from amodal3d.utils import postprocessing_utils
+
+    glb = postprocessing_utils.to_glb(
+        gs,
+        mesh,
+        simplify=mesh_simplify,
+        texture_size=texture_size,
+        verbose=False,
+    )
+    glb.export(export_path)
+    return export_path
+
+
+def save_mesh(mesh_result, filename):
+    vertices = (
+        mesh_result.vertices.cpu().numpy()
+        if hasattr(mesh_result.vertices, "cpu")
+        else mesh_result.vertices
+    )
+    faces = (
+        mesh_result.faces.cpu().numpy()
+        if hasattr(mesh_result.faces, "cpu")
+        else mesh_result.faces
+    )
+    mesh = trimesh.Trimesh(vertices=vertices, faces=faces, process=False)
+    if mesh_result.vertex_attrs is not None:
+        attrs = (
+            mesh_result.vertex_attrs.cpu().numpy()
+            if hasattr(mesh_result.vertex_attrs, "cpu")
+            else mesh_result.vertex_attrs
+        )
+        mesh.visual.vertex_colors = attrs
+    mesh.export(filename)
+
+
+def parse_box(box):
+    values = [float(value) for value in box.split(",")]
+    if len(values) != 4:
+        raise argparse.ArgumentTypeError("box must be x1,y1,x2,y2")
+    if any(value < 0 or value > 1 for value in values):
+        raise argparse.ArgumentTypeError("box coordinates must be normalized to [0, 1]")
+    x1, y1, x2, y2 = values
+    if x2 <= x1 or y2 <= y1:
+        raise argparse.ArgumentTypeError("box must satisfy x2>x1 and y2>y1")
+    return values
+
+
+def make_stair_scene_mask(image, occlusion_boxes=None, save_path=None):
+    width, height = image.size
+    mask = np.full((height, width), VISIBLE_VALUE, dtype=np.uint8)
+    mask[: int(height * 0.08), :] = BACKGROUND_VALUE
+    for x1, y1, x2, y2 in occlusion_boxes or []:
+        left = int(round(x1 * width))
+        top = int(round(y1 * height))
+        right = int(round(x2 * width))
+        bottom = int(round(y2 * height))
+        mask[top:bottom, left:right] = OCCLUDED_VALUE
+    result = Image.fromarray(mask, mode="L")
+    if save_path is not None:
+        result.save(save_path)
+    return result
+
+
+def load_three_value_condition_mask(
+    path: str | Path,
+    *,
+    expected_size: tuple[int, int],
+) -> tuple[Image.Image, Path, dict[str, Any]]:
+    """Load and strictly validate an aligned Amodal3R condition PNG."""
+
+    resolved = resolve_path(path)
+    if not resolved.is_file():
+        raise FileNotFoundError(resolved)
+    with Image.open(resolved) as source:
+        image_format = source.format
+        condition = ImageOps.exif_transpose(source)
+        if image_format != "PNG":
+            raise ValueError(
+                f"Condition mask must be a PNG file; detected {image_format or 'unknown'}"
+            )
+        if condition.mode != "L":
+            raise ValueError(
+                "Condition mask PNG must be single-channel 8-bit grayscale "
+                f"(mode L); got mode {condition.mode}"
+            )
+        if condition.size != expected_size:
+            raise ValueError(
+                "Condition mask/RGB raster mismatch: "
+                f"mask={condition.size}, rgb={expected_size}. Refusing to resize."
+            )
+        values = np.asarray(condition, dtype=np.uint8).copy()
+
+    observed_values, observed_counts = np.unique(values, return_counts=True)
+    observed = {
+        int(value): int(count)
+        for value, count in zip(observed_values.tolist(), observed_counts.tolist())
+    }
+    invalid_values = sorted(set(observed) - set(THREE_VALUE_MASK_VALUES))
+    if invalid_values:
+        raise ValueError(
+            "Condition mask PNG contains invalid pixel values "
+            f"{invalid_values}; allowed exact values are "
+            f"{list(THREE_VALUE_MASK_VALUES)}"
+        )
+    visible_count = observed.get(VISIBLE_VALUE, 0)
+    if visible_count == 0:
+        raise ValueError(
+            "Condition mask PNG must contain at least one visible-target pixel "
+            f"with value {VISIBLE_VALUE}"
+        )
+
+    width, height = expected_size
+    statistics = {
+        "strict_three_value_validation": True,
+        "allowed_values": list(THREE_VALUE_MASK_VALUES),
+        "observed_values": sorted(observed),
+        "width": int(width),
+        "height": int(height),
+        "total_pixel_count": int(values.size),
+        "hidden_pixel_count": observed.get(OCCLUDED_VALUE, 0),
+        "visible_pixel_count": visible_count,
+        "background_pixel_count": observed.get(BACKGROUND_VALUE, 0),
+        "hidden_region_present": observed.get(OCCLUDED_VALUE, 0) > 0,
+    }
+    return Image.fromarray(values, mode="L"), resolved, statistics
+
+
+def square_focus_crop(
+    image: Image.Image,
+    mask: Image.Image,
+    *,
+    padding_ratio: float,
+) -> tuple[Image.Image, Image.Image, dict[str, Any]]:
+    """Crop/pad aligned RGB and mask around the target without distortion."""
+
+    if not math.isfinite(padding_ratio) or padding_ratio < 0:
+        raise ValueError("--focus-crop-padding-ratio must be non-negative")
+    if image.size != mask.size:
+        raise ValueError("Focus crop requires aligned RGB and condition mask")
+
+    values = np.asarray(mask, dtype=np.uint8)
+    target_y, target_x = np.nonzero(values != BACKGROUND_VALUE)
+    if target_x.size == 0:
+        raise ValueError(
+            "Focus crop requires at least one non-background target pixel"
+        )
+
+    bbox_left = int(target_x.min())
+    bbox_top = int(target_y.min())
+    bbox_right = int(target_x.max()) + 1
+    bbox_bottom = int(target_y.max()) + 1
+    bbox_width = bbox_right - bbox_left
+    bbox_height = bbox_bottom - bbox_top
+    side = max(
+        1,
+        int(
+            math.ceil(
+                max(bbox_width, bbox_height)
+                * (1.0 + 2.0 * padding_ratio)
+            )
+        ),
+    )
+    center_x = 0.5 * (bbox_left + bbox_right)
+    center_y = 0.5 * (bbox_top + bbox_bottom)
+    crop_left = int(math.floor(center_x - 0.5 * side))
+    crop_top = int(math.floor(center_y - 0.5 * side))
+    crop_right = crop_left + side
+    crop_bottom = crop_top + side
+
+    source_width, source_height = image.size
+    source_left = max(crop_left, 0)
+    source_top = max(crop_top, 0)
+    source_right = min(crop_right, source_width)
+    source_bottom = min(crop_bottom, source_height)
+    paste_left = source_left - crop_left
+    paste_top = source_top - crop_top
+
+    focused_image = Image.new("RGB", (side, side), (0, 0, 0))
+    focused_mask = Image.new("L", (side, side), BACKGROUND_VALUE)
+    source_box = (source_left, source_top, source_right, source_bottom)
+    focused_image.paste(image.crop(source_box), (paste_left, paste_top))
+    focused_mask.paste(mask.crop(source_box), (paste_left, paste_top))
+
+    focused_values = np.asarray(focused_mask, dtype=np.uint8)
+    observed_values, observed_counts = np.unique(
+        focused_values, return_counts=True
+    )
+    observed = {
+        int(value): int(count)
+        for value, count in zip(
+            observed_values.tolist(), observed_counts.tolist()
+        )
+    }
+    metadata = {
+        "applied": True,
+        "policy": "square_target_bbox_crop_with_background_padding",
+        "padding_ratio": float(padding_ratio),
+        "source_size": [int(source_width), int(source_height)],
+        "target_bbox_xyxy": [
+            bbox_left,
+            bbox_top,
+            bbox_right,
+            bbox_bottom,
+        ],
+        "crop_box_xyxy": [crop_left, crop_top, crop_right, crop_bottom],
+        "source_intersection_xyxy": [
+            source_left,
+            source_top,
+            source_right,
+            source_bottom,
+        ],
+        "output_size": [side, side],
+        "observed_values": sorted(observed),
+        "hidden_pixel_count": observed.get(OCCLUDED_VALUE, 0),
+        "visible_pixel_count": observed.get(VISIBLE_VALUE, 0),
+        "background_pixel_count": observed.get(BACKGROUND_VALUE, 0),
+    }
+    return focused_image, focused_mask, metadata
+
+
+def load_inputs(args, output_dir):
+    backend_rgb_path, input_provenance = select_backend_rgb(args)
+    with Image.open(backend_rgb_path) as source:
+        image = ImageOps.exif_transpose(source).convert("RGB")
+    if args.mask:
+        mask_source = resolve_path(args.mask)
+    else:
+        mask_path = output_dir / "auto_stair_mask.png"
+        make_stair_scene_mask(image, args.occlusion_box, mask_path)
+        mask_source = mask_path.resolve()
+    mask, mask_source, mask_statistics = load_three_value_condition_mask(
+        mask_source,
+        expected_size=image.size,
+    )
+    focus_crop_padding_ratio = getattr(
+        args, "focus_crop_padding_ratio", None
+    )
+    if focus_crop_padding_ratio is not None:
+        source_mask_statistics = dict(mask_statistics)
+        image, mask, focus_crop = square_focus_crop(
+            image,
+            mask,
+            padding_ratio=float(focus_crop_padding_ratio),
+        )
+        mask_statistics = {
+            **mask_statistics,
+            "width": int(mask.width),
+            "height": int(mask.height),
+            "total_pixel_count": int(mask.width * mask.height),
+            "observed_values": focus_crop["observed_values"],
+            "hidden_pixel_count": focus_crop["hidden_pixel_count"],
+            "visible_pixel_count": focus_crop["visible_pixel_count"],
+            "background_pixel_count": focus_crop["background_pixel_count"],
+            "hidden_region_present": focus_crop["hidden_pixel_count"] > 0,
+            "focus_crop": focus_crop,
+            "pre_focus_crop_statistics": source_mask_statistics,
+        }
+    return (
+        image,
+        mask,
+        mask_source,
+        mask_statistics,
+        backend_rgb_path,
+        input_provenance,
+    )
+
+
+def require_cuda(torch_module: Any | None = None) -> dict[str, Any]:
+    """Fail before model loading unless the process has a usable CUDA allocation."""
+
+    if torch_module is None:
+        try:
+            import torch as torch_module
+        except ImportError as exc:
+            raise RuntimeError(
+                "Amodal3R visual 3D requires PyTorch with CUDA support"
+            ) from exc
+    cuda = getattr(torch_module, "cuda", None)
+    if cuda is None or not cuda.is_available():
+        raise RuntimeError(
+            "Amodal3R visual 3D requires an available CUDA GPU for learned "
+            "generation and diff_gaussian_rasterization. Run this command inside "
+            "a Slurm GPU allocation."
+        )
+    device_count = getattr(cuda, "device_count", lambda: 1)()
+    torch_version = getattr(torch_module, "__version__", None)
+    version_namespace = getattr(torch_module, "version", None)
+    return {
+        "required": True,
+        "available": True,
+        "device_type": "cuda",
+        "device_count": int(device_count),
+        "torch_version": str(torch_version) if torch_version is not None else None,
+        "torch_cuda_build": (
+            str(getattr(version_namespace, "cuda"))
+            if version_namespace is not None
+            and getattr(version_namespace, "cuda", None) is not None
+            else None
+        ),
+    }
+
+
+def require_gpu_renderers(
+    *,
+    allow_gaussian_only: bool,
+    find_spec=importlib.util.find_spec,
+    import_module=importlib.import_module,
+) -> dict[str, Any]:
+    """Preflight the CUDA rasterizers before loading the Amodal3R weights."""
+
+    gaussian_available = find_spec("diff_gaussian_rasterization") is not None
+    if not gaussian_available:
+        raise RuntimeError(
+            "Amodal3R requires diff_gaussian_rasterization for the primary "
+            "CUDA rotating render."
+        )
+    try:
+        import_module("diff_gaussian_rasterization")
+    except Exception as exc:
+        raise RuntimeError(
+            "diff_gaussian_rasterization is installed but its CUDA extension "
+            "could not be imported."
+        ) from exc
+    mesh_available = find_spec("nvdiffrast") is not None
+    if not mesh_available and not allow_gaussian_only:
+        raise RuntimeError(
+            "Full GPU rendering requires nvdiffrast for the dense FlexiCubes "
+            "mesh rotation. Install the project --nvdiffrast dependency, or use "
+            "--allow-gaussian-only only for an explicit debug run."
+        )
+    mesh_context_ready = False
+    if mesh_available:
+        try:
+            dr = import_module("nvdiffrast.torch")
+            context = dr.RasterizeCudaContext(device="cuda")
+            del context
+            mesh_context_ready = True
+        except Exception as exc:
+            raise RuntimeError(
+                "nvdiffrast is installed but its CUDA raster context could not "
+                "be created on the allocated GPU."
+            ) from exc
+    return {
+        "gaussian": {
+            "package": "diff_gaussian_rasterization",
+            "available": gaussian_available,
+            "required": True,
+            "device": "cuda",
+            "runtime_import_succeeded": True,
+        },
+        "dense_mesh": {
+            "package": "nvdiffrast",
+            "available": mesh_available,
+            "required": not allow_gaussian_only,
+            "device": "cuda" if mesh_available else None,
+            "runtime_import_succeeded": mesh_available,
+            "cuda_context_preflight_succeeded": mesh_context_ready,
+        },
+        "cpu_render_fallback_allowed": False,
+        "gaussian_only_debug_mode": bool(allow_gaussian_only),
+    }
+
+
+def write_gif_atomic(path: Path, frames: list[np.ndarray], *, fps: int) -> None:
+    temporary = path.with_name(f".{path.stem}.{os.getpid()}.tmp.gif")
+    try:
+        imageio.mimsave(
+            temporary,
+            frames,
+            duration=1000.0 / float(fps),
+            loop=0,
+        )
+        os.replace(temporary, path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def copy_file_atomic(source: Path, destination: Path) -> None:
+    """Atomically materialize a byte-identical compatibility artifact."""
+
+    temporary = destination.with_name(
+        f".{destination.stem}.{os.getpid()}.tmp{destination.suffix}"
+    )
+    try:
+        shutil.copyfile(source, temporary)
+        os.replace(temporary, destination)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+
+def inspect_gif(path: Path) -> dict[str, Any]:
+    with Image.open(path) as image:
+        return {
+            "path": path.name,
+            "frames": int(getattr(image, "n_frames", 1)),
+            "width": int(image.width),
+            "height": int(image.height),
+        }
+
+
+def validate_render_artifacts(
+    *,
+    output_dir: Path,
+    video_frames: int,
+    nviews: int,
+    dense_mesh_rendered: bool,
+    mesh_face_count: int,
+) -> dict[str, Any]:
+    """Validate the full-GPU publication contract before writing manifest.json."""
+
+    gaussian = inspect_gif(output_dir / "sample_gaussian.gif")
+    combined = inspect_gif(output_dir / "sample_multi.gif")
+    if gaussian["frames"] != video_frames or combined["frames"] != video_frames:
+        raise RuntimeError(
+            "GPU GIF frame-count mismatch: "
+            f"gaussian={gaussian['frames']}, combined={combined['frames']}, "
+            f"expected={video_frames}"
+        )
+    # The 9527 reference contract uses sample_multi.gif as a compatibility
+    # alias for the source-colored Gaussian render.  Dense-mesh normal maps are
+    # diagnostics and must never widen or recolor the primary presentation.
+    expected_combined_width = gaussian["width"]
+    if (
+        combined["width"] != expected_combined_width
+        or combined["height"] != gaussian["height"]
+    ):
+        raise RuntimeError(
+            "Reference-compatible GIF dimensions do not match the Gaussian render"
+        )
+    if sha256_file(output_dir / "sample_gaussian.gif") != sha256_file(
+        output_dir / "sample_multi.gif"
+    ):
+        raise RuntimeError(
+            "sample_multi.gif must be a byte-identical compatibility alias of "
+            "the source-colored sample_gaussian.gif"
+        )
+    gaussian_views = [
+        output_dir / f"{index:03d}_gs.png" for index in range(nviews)
+    ]
+    if not all(path.is_file() and path.stat().st_size > 0 for path in gaussian_views):
+        raise RuntimeError("GPU Gaussian multiview output is incomplete")
+
+    mesh_gif = None
+    mesh_views: list[Path] = []
+    if dense_mesh_rendered:
+        mesh_gif = inspect_gif(output_dir / "sample_mesh.gif")
+        if (
+            mesh_gif["frames"] != video_frames
+            or mesh_gif["width"] != gaussian["width"]
+            or mesh_gif["height"] != gaussian["height"]
+        ):
+            raise RuntimeError("GPU dense-mesh GIF does not align with Gaussian GIF")
+        mesh_views = [
+            output_dir / f"{index:03d}_mesh.png" for index in range(nviews)
+        ]
+        if not all(path.is_file() and path.stat().st_size > 0 for path in mesh_views):
+            raise RuntimeError("GPU dense-mesh multiview output is incomplete")
+    if mesh_face_count <= 0:
+        raise RuntimeError("FlexiCubes output contains no triangle faces")
+    contact_sheet = output_dir / "multiview_contact_sheet.jpg"
+    if not contact_sheet.is_file() or contact_sheet.stat().st_size <= 0:
+        raise RuntimeError("GPU multiview contact sheet is missing")
+    with Image.open(contact_sheet) as sheet:
+        expected_sheet_size = (
+            gaussian["width"] * 2,
+            gaussian["height"] * ((nviews + 1) // 2),
+        )
+        if sheet.size != expected_sheet_size:
+            raise RuntimeError(
+                "Primary contact sheet must use only source-colored Gaussian "
+                f"views in a 2-column layout: got={sheet.size}, "
+                f"expected={expected_sheet_size}"
+            )
+    return {
+        "validated": True,
+        "gaussian_gif": gaussian,
+        "mesh_gif": mesh_gif,
+        "combined_gif": combined,
+        "combined_gif_is_byte_identical_gaussian_alias": True,
+        "contact_sheet_layout": "gaussian_color_only_2_columns",
+        "gaussian_view_count": len(gaussian_views),
+        "mesh_view_count": len(mesh_views),
+        "dense_mesh_rendered_on_gpu": dense_mesh_rendered,
+        "mesh_face_count": int(mesh_face_count),
+        "cpu_render_fallback_used": False,
+    }
+
+
+def build_output_manifest(
+    *,
+    args: argparse.Namespace,
+    input_provenance: dict[str, Any],
+    mask_source: str | Path,
+    mask_statistics: dict[str, Any],
+    cuda_runtime: dict[str, Any],
+    gpu_renderer_runtime: dict[str, Any],
+    render_validation: dict[str, Any],
+    mesh_gif: str | None,
+    nvdiffrast_available: bool,
+    mesh_renderer_mode: str,
+    glb_export_mode: str | None,
+) -> dict[str, Any]:
+    """Build the portable visual-candidate manifest and evidence policy."""
+
+    return {
+        "schema_version": "accessibilityamodal_visual_3d_candidate_v1",
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "input_provenance": input_provenance,
+        "three_value_mask": portable_file_record(resolve_path(mask_source)),
+        "three_value_mask_statistics": dict(mask_statistics),
+        "third_party_backend_provenance": {
+            "name": "Amodal3R",
+            "python_package": "amodal3d",
+            "pipeline_class": "Amodal3RImageTo3DPipeline",
+            "model_identifier_or_path": args.model,
+            "upstream_identity_preserved": True,
+        },
+        "representation_contract": {
+            "primary_representation": "Amodal3R Gaussian",
+            "primary_render_backend": "CUDA diff_gaussian_rasterization",
+            "primary_render_device": "cuda",
+            "primary_output": "sample_gaussian.gif",
+            "reference_compatible_output": "sample_multi.gif",
+            "reference_compatible_output_matches_primary": True,
+            "primary_appearance": (
+                "quality_gated_obstacle_removed_color_preserving_original_texture"
+                if input_provenance["conditioning_rgb_mode"] == "completed"
+                else "source_rgb_conditioned_color"
+            ),
+            "appearance_conditioning_mode": input_provenance[
+                "conditioning_rgb_mode"
+            ],
+            "primary_contact_sheet": "multiview_contact_sheet.jpg",
+            "primary_contact_sheet_content": "gaussian_color_only",
+            "paired_dense_geometry": "FlexiCubes triangle mesh",
+            "paired_dense_geometry_output": "mesh.ply",
+            "paired_dense_geometry_render": (
+                "sample_mesh.gif" if nvdiffrast_available else None
+            ),
+            "paired_dense_geometry_render_role": (
+                "diagnostic_normal_map_only_not_source_rgb_texture"
+                if nvdiffrast_available
+                else None
+            ),
+            "interactive_textured_surface": (
+                "mesh.glb" if args.export_glb else None
+            ),
+            "interactive_texture_source": (
+                "GPU Gaussian appearance baked to UV/PBR base-color texture"
+                if args.export_glb
+                else None
+            ),
+            "vggt_is_primary": False,
+            "discrete_point_cloud_is_primary": False,
+        },
+        "cuda_runtime": dict(cuda_runtime),
+        "gpu_renderer_runtime": dict(gpu_renderer_runtime),
+        "render_validation": dict(render_validation),
+        "seed": args.seed,
+        "nviews": args.nviews,
+        "video_frames": args.video_frames,
+        "output_kind": (
+            "AccessibilityAmodal learned visual candidate via the licensed "
+            "third-party Amodal3R backend"
+        ),
+        "outputs": {
+            "combined_gif": "sample_multi.gif",
+            "gaussian_gif": "sample_gaussian.gif",
+            "mesh_gif": mesh_gif,
+            "mesh_normal_diagnostic_gif": mesh_gif,
+            "contact_sheet": "multiview_contact_sheet.jpg",
+            "mesh": "mesh.ply",
+            "glb": "mesh.glb" if args.export_glb else None,
+            "conditioning_rgb_model_input": "conditioning_rgb_model_input.png",
+            "condition_mask_model_input": "condition_mask_model_input.png",
+        },
+        "nvdiffrast_available": nvdiffrast_available,
+        "mesh_renderer_mode": mesh_renderer_mode,
+        "glb_export_mode": glb_export_mode,
+        "metric_geometry": False,
+        "passability_evidence": False,
+        "automatic_passability_claim": False,
+        "human_review_required": True,
+        "evidence_policy": {
+            "role": "learned_visual_candidate_only",
+            "metric_geometry": False,
+            "passability_evidence": False,
+            "automatic_passability_claim": False,
+            "warning": (
+                "This learned visual 3D candidate is not calibrated geometry and "
+                "must not be used to decide whether a person can pass."
+            ),
+        },
+    }
+
+
+def run(args):
+    output_dir = Path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    # manifest.json is the success marker. Remove stale primary markers before a
+    # rerun so a failed GPU mesh pass cannot be mistaken for a complete result.
+    for filename in (
+        "manifest.json",
+        "sample_multi.gif",
+        "sample_mesh.gif",
+        "mesh.glb",
+    ):
+        (output_dir / filename).unlink(missing_ok=True)
+    (
+        image,
+        mask,
+        mask_source,
+        mask_statistics,
+        backend_rgb_path,
+        input_provenance,
+    ) = load_inputs(args, output_dir)
+    image.save(output_dir / "conditioning_rgb_model_input.png")
+    mask.save(output_dir / "condition_mask_model_input.png")
+    cuda_runtime = require_cuda()
+    gpu_renderer_runtime = require_gpu_renderers(
+        allow_gaussian_only=args.allow_gaussian_only,
+    )
+    nvdiffrast_available = bool(
+        gpu_renderer_runtime["dense_mesh"]["available"]
+    )
+    print(f"Original image: {args.image}")
+    print(f"Learned visual backend RGB: {backend_rgb_path}")
+    print(f"Backend RGB role: {input_provenance['backend_rgb_role']}")
+    if input_provenance["completion_inputs_ignored"]:
+        print(
+            "Completion RGB arguments were supplied but ignored because "
+            "--conditioning-rgb defaults to original."
+        )
+    print(f"Mask: {mask_source}")
+    print(f"Output dir: {output_dir}")
+
+    pipeline_class, render_utils = load_backend_runtime()
+    pipeline = pipeline_class.from_pretrained(args.model)
+    pipeline.cuda()
+    outputs = pipeline.run_multi_image(
+        [image],
+        [mask],
+        seed=args.seed,
+        sparse_structure_sampler_params={"steps": args.ss_steps, "cfg_strength": args.ss_cfg},
+        slat_sampler_params={"steps": args.slat_steps, "cfg_strength": args.slat_cfg},
+        erode_kernel_size=args.erode_kernel_size,
+    )
+
+    video_gs = render_utils.render_video(
+        outputs["gaussian"][0],
+        bg_color=(1, 1, 1),
+        num_frames=args.video_frames,
+    )["color"]
+    write_gif_atomic(output_dir / "sample_gaussian.gif", video_gs, fps=24)
+    gaussian = outputs["gaussian"][0]
+    multi_view_gs, _, _ = render_utils.render_multiview(
+        gaussian, nviews=args.nviews, bg_color=(1, 1, 1)
+    )
+    mesh = outputs["mesh"][0]
+    for index, output in enumerate(multi_view_gs["color"]):
+        output = cv2.cvtColor(output, cv2.COLOR_RGB2BGR)
+        cv2.imwrite(str(output_dir / f"{index:03d}_gs.png"), output)
+    mesh_path = output_dir / "mesh.ply"
+    save_mesh(mesh, mesh_path)
+    mesh_face_count = int(mesh.faces.shape[0])
+
+    mesh_gif: str | None = None
+    mesh_renderer_mode = "skipped: explicit Gaussian-only debug mode"
+    if nvdiffrast_available:
+        video_mesh = render_utils.render_video(
+            mesh,
+            bg_color=(1, 1, 1),
+            num_frames=args.video_frames,
+        )["normal"]
+        write_gif_atomic(output_dir / "sample_mesh.gif", video_mesh, fps=24)
+        copy_file_atomic(
+            output_dir / "sample_gaussian.gif",
+            output_dir / "sample_multi.gif",
+        )
+        multi_view_mesh, _, _ = render_utils.render_multiview(
+            mesh, nviews=args.nviews, bg_color=(1, 1, 1)
+        )
+        for index, output in enumerate(multi_view_mesh["normal"]):
+            output = cv2.cvtColor(output, cv2.COLOR_RGB2BGR)
+            cv2.imwrite(str(output_dir / f"{index:03d}_mesh.png"), output)
+        previews = list(multi_view_gs["color"])
+        mesh_gif = "sample_mesh.gif"
+        mesh_renderer_mode = "nvdiffrast normal-map diagnostic rendering"
+    else:
+        previews = list(multi_view_gs["color"])
+        copy_file_atomic(
+            output_dir / "sample_gaussian.gif",
+            output_dir / "sample_multi.gif",
+        )
+
+    rows = []
+    for start in range(0, len(previews), 2):
+        row = previews[start : start + 2]
+        if len(row) == 1:
+            row.append(np.full_like(row[0], 255))
+        rows.append(np.concatenate(row, axis=1))
+    contact_sheet = np.concatenate(rows, axis=0)
+    contact_sheet_path = output_dir / "multiview_contact_sheet.jpg"
+    temporary_contact_sheet = contact_sheet_path.with_name(
+        f".{contact_sheet_path.stem}.{os.getpid()}.tmp.jpg"
+    )
+    try:
+        Image.fromarray(contact_sheet).save(temporary_contact_sheet, quality=92)
+        os.replace(temporary_contact_sheet, contact_sheet_path)
+    finally:
+        temporary_contact_sheet.unlink(missing_ok=True)
+    glb_export_mode = None
+    if args.export_glb:
+        if nvdiffrast_available:
+            extract_glb(
+                outputs["gaussian"][0],
+                outputs["mesh"][0],
+                mesh_simplify=args.mesh_simplify,
+                texture_size=args.texture_size,
+                export_path=str(output_dir / "mesh.glb"),
+            )
+            glb_export_mode = "Amodal3R textured GLB"
+        else:
+            raise RuntimeError(
+                "--export-glb requires nvdiffrast; CPU GLB fallback is disabled "
+                "by the full-GPU rendering contract."
+            )
+    render_validation = validate_render_artifacts(
+        output_dir=output_dir,
+        video_frames=args.video_frames,
+        nviews=args.nviews,
+        dense_mesh_rendered=nvdiffrast_available,
+        mesh_face_count=mesh_face_count,
+    )
+    manifest = build_output_manifest(
+        args=args,
+        input_provenance=input_provenance,
+        mask_source=mask_source,
+        mask_statistics=mask_statistics,
+        cuda_runtime=cuda_runtime,
+        gpu_renderer_runtime=gpu_renderer_runtime,
+        render_validation=render_validation,
+        mesh_gif=mesh_gif,
+        nvdiffrast_available=nvdiffrast_available,
+        mesh_renderer_mode=mesh_renderer_mode,
+        glb_export_mode=glb_export_mode,
+    )
+    (output_dir / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    print("Done.")
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        description="Run the AccessibilityAmodal visual-3D backend adapter."
+    )
+    parser.add_argument(
+        "--image",
+        required=True,
+        help=(
+            "Canonical original RGB. It remains provenance/geometry source even "
+            "when an accepted selected 2D completion drives this visual backend."
+        ),
+    )
+    parser.add_argument(
+        "--conditioning-rgb",
+        choices=("original", "completed"),
+        default="original",
+        help=(
+            "RGB used to condition Amodal3R. Defaults to the canonical original. "
+            "Use 'completed' explicitly to opt in to a quality-gated completion."
+        ),
+    )
+    parser.add_argument(
+        "--completed-image",
+        default=None,
+        help=(
+            "Selected 2D completion used only with --conditioning-rgb completed. "
+            "Requires an accepted --completion-manifest."
+        ),
+    )
+    parser.add_argument(
+        "--completion-manifest",
+        default=None,
+        help=(
+            "2D manifest proving --completed-image is the selected candidate. "
+            "Required only with --conditioning-rgb completed."
+        ),
+    )
+    parser.add_argument(
+        "--mask",
+        default=None,
+        help="Optional three-value mask: white background, gray visible, black occluded.",
+    )
+    parser.add_argument(
+        "--focus-crop-padding-ratio",
+        type=float,
+        default=None,
+        help=(
+            "Optionally crop/pad RGB and mask to a square around the modeled "
+            "target before Amodal3R's 518x518 resize. This preserves source "
+            "aspect ratio and makes small target surfaces more prominent."
+        ),
+    )
+    parser.add_argument("--output-dir", default="./output/accessibilityamodal/visual_candidate")
+    parser.add_argument("--model", default="Sm0kyWu/Amodal3R")
+    parser.add_argument("--occlusion-box", action="append", type=parse_box, default=[])
+    parser.add_argument("--seed", type=int, default=1)
+    parser.add_argument("--ss-steps", type=int, default=12)
+    parser.add_argument("--ss-cfg", type=float, default=7.5)
+    parser.add_argument("--slat-steps", type=int, default=12)
+    parser.add_argument("--slat-cfg", type=float, default=3.0)
+    parser.add_argument("--erode-kernel-size", type=int, default=3)
+    parser.add_argument("--nviews", type=int, default=8)
+    parser.add_argument("--video-frames", type=int, default=120)
+    parser.add_argument(
+        "--allow-gaussian-only",
+        action="store_true",
+        help=(
+            "Explicit debug escape hatch when nvdiffrast is unavailable. "
+            "The default requires both CUDA Gaussian and CUDA dense-mesh renders."
+        ),
+    )
+    parser.add_argument("--export-glb", action="store_true")
+    parser.add_argument("--mesh-simplify", type=float, default=0.5)
+    parser.add_argument("--texture-size", type=int, default=1024)
+    return parser
+
+
+if __name__ == "__main__":
+    run(build_parser().parse_args())

tools/accessibility_3d_variants.py

@@ -0,0 +1,858 @@
+#!/usr/bin/env python3
+"""Build face-rendered, solidified, and canonical 3D views for one result."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+import trimesh
+from PIL import Image, ImageDraw
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from tools.build_accessibility_solid_mesh_showcase import (  # noqa: E402
+    CONTINUOUS_SURFACE_CATEGORIES,
+    build_canonical_staircase_prism_mesh,
+    build_continuous_stair_mesh,
+    build_solid_mesh,
+    clean_target_mask,
+    continuous_depth_for_category,
+    fit_plane,
+    plane_depth_for_pixels,
+    prepare_texture,
+    read_json,
+    read_mask,
+    render_mesh_frame,
+    trusted_stair_edges_from_manifest,
+    write_ply,
+    write_turntable_gif,
+)
+from accessibilityamodal.reconstruct import camera_intrinsics, pixels_to_points  # noqa: E402
+
+
+def continuous_presentation_mask(
+    target_mask: np.ndarray,
+    *,
+    maximum_hull_expansion_ratio: float = 1.8,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """Return a hole-free, category-constrained surface presentation mask.
+
+    The semantic/review masks remain untouched on disk.  This mask is used only
+    for the nonmetric solid visualization so that segmentation notches do not
+    become vertical person-shaped walls.  A modest convex hull is accepted for
+    perspective walkway footprints; strongly concave routes keep their outer
+    contour and only close internal holes.
+    """
+
+    target = np.asarray(target_mask, dtype=bool)
+    if target.ndim != 2:
+        raise ValueError("target_mask must be a 2D mask")
+    if maximum_hull_expansion_ratio < 1:
+        raise ValueError("maximum_hull_expansion_ratio must be at least 1")
+    pixels = int(target.sum())
+    if pixels == 0:
+        return target.copy(), {
+            "policy": "unchanged_empty_target",
+            "source_pixel_count": 0,
+            "presentation_pixel_count": 0,
+            "hull_expansion_ratio": None,
+        }
+
+    external = np.zeros_like(target, dtype=np.uint8)
+    contours, _ = cv2.findContours(
+        target.astype(np.uint8),
+        cv2.RETR_EXTERNAL,
+        cv2.CHAIN_APPROX_SIMPLE,
+    )
+    cv2.drawContours(external, contours, -1, 1, cv2.FILLED)
+    external_mask = external.astype(bool)
+    ys, xs = np.where(external_mask)
+    points = np.column_stack([xs, ys]).astype(np.int32)
+    hull = np.zeros_like(external, dtype=np.uint8)
+    if points.shape[0] >= 3:
+        cv2.fillConvexPoly(hull, cv2.convexHull(points), 1)
+    else:
+        hull[external_mask] = 1
+    hull_mask = hull.astype(bool)
+    hull_ratio = int(hull_mask.sum()) / max(int(external_mask.sum()), 1)
+    use_hull = hull_ratio <= maximum_hull_expansion_ratio
+    presentation = hull_mask if use_hull else external_mask
+    return presentation, {
+        "policy": (
+            "bounded_convex_support_presentation"
+            if use_hull
+            else "external_contour_hole_fill_due_to_ambiguous_concavity"
+        ),
+        "source_pixel_count": pixels,
+        "external_contour_pixel_count": int(external_mask.sum()),
+        "presentation_pixel_count": int(presentation.sum()),
+        "hull_expansion_ratio": round(hull_ratio, 8),
+        "maximum_hull_expansion_ratio": float(maximum_hull_expansion_ratio),
+        "semantic_mask_unchanged": True,
+        "metric_geometry": False,
+        "human_review_required": True,
+    }
+
+
+def idealized_continuous_presentation_depth(
+    depth: np.ndarray,
+    presentation_mask: np.ndarray,
+    visible_mask: np.ndarray | None,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """Fit one bounded support plane for a clean, nonmetric solid preview."""
+
+    source = np.asarray(depth, dtype=np.float32)
+    target = np.asarray(presentation_mask, dtype=bool)
+    visible = target if visible_mask is None else (
+        np.asarray(visible_mask, dtype=bool) & target
+    )
+    h, w = source.shape
+    fx, fy, cx, cy = camera_intrinsics(w, h, None, None, None, None)
+    points = pixels_to_points(source, fx, fy, cx, cy)
+    fit_mask = visible & np.isfinite(source) & (source > 0)
+    plane = fit_plane(points[fit_mask])
+    if plane is None:
+        fallback, metadata = continuous_depth_for_category(
+            source,
+            target,
+            visible_mask,
+            "walkway",
+        )
+        return fallback, {
+            **metadata,
+            "presentation_depth_policy": "fallback_continuous_depth_plane_fit_failed",
+            "human_review_required": True,
+        }
+
+    observed = source[fit_mask]
+    low, high = np.percentile(observed, [1, 99])
+    lower_bound = max(1e-4, 0.50 * float(low))
+    upper_bound = max(lower_bound + 1e-4, 1.50 * float(high))
+    plane_depth = plane_depth_for_pixels(
+        source.shape,
+        plane,
+        fx,
+        fy,
+        cx,
+        cy,
+    )
+    invalid = target & (~np.isfinite(plane_depth) | (plane_depth <= 0))
+    bounded_plane = np.clip(plane_depth, lower_bound, upper_bound)
+    result = source.copy()
+    result[target & ~invalid] = bounded_plane[target & ~invalid]
+    if invalid.any():
+        result[invalid] = float(np.median(observed))
+    clamped = target & (
+        (plane_depth < lower_bound)
+        | (plane_depth > upper_bound)
+    )
+    return result, {
+        "surface_model": "bounded_robust_single_plane_presentation",
+        "fit_points": int(fit_mask.sum()),
+        "plane_normal": [float(value) for value in plane[0]],
+        "plane_d": float(plane[1]),
+        "presentation_pixels": int(target.sum()),
+        "invalid_plane_pixels_replaced": int(invalid.sum()),
+        "bounded_plane_pixels": int(clamped.sum()),
+        "depth_bounds": [lower_bound, upper_bound],
+        "presentation_depth_policy": (
+            "visible_target_plane_extended_over_nonmetric_presentation_mask"
+        ),
+        "metric_geometry": False,
+        "safe_passage_claim": False,
+        "human_review_required": True,
+    }
+
+
+def load_ply(path: Path) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    mesh = trimesh.load(path, process=False)
+    if not isinstance(mesh, trimesh.Trimesh):
+        raise ValueError(f"Expected one triangle mesh in {path}")
+    vertices = np.asarray(mesh.vertices, dtype=np.float32)
+    faces = np.asarray(mesh.faces, dtype=np.int64)
+    vertex_colors = np.asarray(mesh.visual.vertex_colors)
+    if vertex_colors.ndim == 2 and vertex_colors.shape[0] == len(vertices):
+        colors = vertex_colors[:, :3].astype(np.uint8)
+    else:
+        colors = np.full((len(vertices), 3), (190, 190, 185), dtype=np.uint8)
+    return vertices, colors, faces
+
+
+def export_glb(
+    path: Path,
+    vertices: np.ndarray,
+    colors: np.ndarray,
+    faces: np.ndarray,
+) -> dict[str, Any]:
+    rgba = np.concatenate(
+        [colors.astype(np.uint8), np.full((len(colors), 1), 255, dtype=np.uint8)],
+        axis=1,
+    )
+    mesh = trimesh.Trimesh(
+        vertices=vertices,
+        faces=faces,
+        vertex_colors=rgba,
+        process=False,
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    mesh.export(path)
+    return {
+        "watertight": bool(mesh.is_watertight),
+        "euler_number": int(mesh.euler_number),
+        "bounds": np.asarray(mesh.bounds).round(6).tolist(),
+    }
+
+
+def save_variant(
+    output_dir: Path,
+    name: str,
+    title: str,
+    vertices: np.ndarray,
+    colors: np.ndarray,
+    faces: np.ndarray,
+    *,
+    sample_id: str,
+    category: str,
+    frames: int,
+    duration_ms: int,
+    size: tuple[int, int],
+    pitch: float,
+    source_ply: Path | None = None,
+    render_outputs: bool = True,
+) -> dict[str, Any]:
+    variant_dir = output_dir / name
+    variant_dir.mkdir(parents=True, exist_ok=True)
+    ply_path = source_ply or variant_dir / f"{name}.ply"
+    if source_ply is None:
+        write_ply(ply_path, vertices, colors, faces)
+    gif_path = variant_dir / f"{name}_slow.gif"
+    preview_path = variant_dir / f"{name}_preview.jpg"
+    glb_path = variant_dir / f"{name}.glb"
+    if render_outputs:
+        write_turntable_gif(
+            gif_path,
+            vertices,
+            colors,
+            faces,
+            sample_id=sample_id,
+            category=f"{category} | {title}",
+            frames=frames,
+            size=size,
+            pitch=pitch,
+            duration_ms=duration_ms,
+        )
+        render_mesh_frame(
+            vertices,
+            colors,
+            faces,
+            size=size,
+            yaw=35.0,
+            pitch=pitch,
+            title=f"{sample_id} | {title}",
+        ).save(preview_path, quality=94)
+    glb_info = export_glb(glb_path, vertices, colors, faces)
+    return {
+        "name": name,
+        "title": title,
+        "vertices": int(len(vertices)),
+        "faces": int(len(faces)),
+        "ply": str(ply_path),
+        "glb": str(glb_path),
+        "gif": str(gif_path) if render_outputs else None,
+        "preview": str(preview_path) if render_outputs else None,
+        **glb_info,
+    }
+
+
+def build_contact_sheet(path: Path, rows: list[dict[str, Any]]) -> None:
+    previews = [Image.open(row["preview"]).convert("RGB") for row in rows]
+    width = max(image.width for image in previews)
+    label_height = 42
+    height = sum(image.height + label_height for image in previews)
+    sheet = Image.new("RGB", (width, height), "white")
+    draw = ImageDraw.Draw(sheet)
+    top = 0
+    for image, row in zip(previews, rows):
+        sheet.paste(image, (0, top + label_height))
+        draw.text(
+            (10, top + 10),
+            f"{row['title']} | {row['vertices']} vertices | {row['faces']} faces",
+            fill=(20, 20, 20),
+        )
+        top += image.height + label_height
+    path.parent.mkdir(parents=True, exist_ok=True)
+    sheet.save(path, quality=94)
+
+
+def portable_path(path: str | Path, anchor: Path) -> str:
+    return Path(os.path.relpath(Path(path).resolve(), anchor.resolve())).as_posix()
+
+
+def portable_variant_row(row: dict[str, Any], anchor: Path) -> dict[str, Any]:
+    portable = dict(row)
+    for key in ("ply", "glb", "gif", "preview"):
+        value = portable.get(key)
+        if value:
+            portable[key] = portable_path(value, anchor)
+    return portable
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def portable_file_record(path: Path, anchor: Path) -> dict[str, Any]:
+    resolved = path.expanduser().resolve()
+    return {
+        "path": portable_path(resolved, anchor),
+        "sha256": sha256_file(resolved),
+        "bytes": int(resolved.stat().st_size),
+    }
+
+
+def resolve_declared_path(value: Any, base_dir: Path) -> Path | None:
+    if not isinstance(value, str) or not value:
+        return None
+    path = Path(value).expanduser()
+    return path if path.is_absolute() else base_dir / path
+
+
+def _portable_model_identity(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    allowed = {
+        "model_id",
+        "family",
+        "encoder",
+        "metric_training_dataset",
+        "checkpoint_filename",
+        "checkpoint_sha256",
+        "selection_policy",
+        "license",
+        "third_party",
+        "revision",
+        "revision_review_required_before_public_release",
+    }
+    identity = {
+        key: item
+        for key, item in value.items()
+        if key in allowed and isinstance(item, (str, int, float, bool, type(None)))
+    }
+    return identity or None
+
+
+def load_depth_context(
+    geometry_dir: Path,
+) -> tuple[dict[str, Any], Path | None]:
+    """Read the depth sidecar without promoting monocular scale to truth."""
+
+    candidates = (
+        geometry_dir.parent / "depth_manifest.json",
+        geometry_dir / "depth_manifest.json",
+    )
+    manifest_path = next((path for path in candidates if path.is_file()), None)
+    payload: dict[str, Any] = {}
+    if manifest_path is not None:
+        value = read_json(manifest_path)
+        if not isinstance(value, dict):
+            raise ValueError(f"Depth manifest must contain one JSON object: {manifest_path}")
+        payload = value
+
+    raw_model = payload.get("model")
+    model = raw_model if isinstance(raw_model, str) else None
+    if model and Path(model).is_absolute():
+        model = Path(model).name
+    checkpoint = payload.get("checkpoint")
+    checkpoint_path = resolve_declared_path(
+        checkpoint,
+        manifest_path.parent if manifest_path is not None else geometry_dir,
+    )
+    checkpoint_name = (
+        Path(checkpoint).name
+        if isinstance(checkpoint, str) and checkpoint
+        else None
+    )
+    checkpoint_sha256 = (
+        sha256_file(checkpoint_path)
+        if checkpoint_path is not None and checkpoint_path.is_file()
+        else None
+    )
+    model_identity = _portable_model_identity(payload.get("model_identity"))
+    if model_identity is None and model:
+        # Older depth manifests predate the structured identity object.  Keep
+        # their declared model identifier instead of silently dropping it.
+        model_identity = {"model_id": model}
+    if (
+        model_identity is None
+        and payload.get("engine") == "depth_anything_v2"
+        and checkpoint_name == "depth_anything_v2_metric_hypersim_vitl.pth"
+    ):
+        model_identity = {
+            "model_id": "Depth-Anything-V2-Metric-Hypersim-Large",
+            "family": "Depth Anything V2",
+            "encoder": payload.get("encoder") or "vitl",
+            "metric_training_dataset": "Hypersim",
+            "checkpoint_filename": checkpoint_name,
+            "checkpoint_sha256": checkpoint_sha256,
+            "selection_policy": (
+                "best_available_local_single_image_metric_depth_model"
+            ),
+        }
+    metric_depth_value = payload.get("metric_depth")
+    if metric_depth_value not in (None, True, False):
+        raise ValueError(
+            "depth_manifest.metric_depth must be a JSON boolean or null: "
+            f"{manifest_path}"
+        )
+    metric_style = metric_depth_value is True
+    return {
+        "manifest_available": manifest_path is not None,
+        "engine": payload.get("engine"),
+        "model": model,
+        "model_identity": model_identity,
+        "checkpoint_filename": checkpoint_name,
+        "checkpoint_sha256": checkpoint_sha256,
+        "encoder": payload.get("encoder"),
+        "metric_depth_manifest_value": metric_depth_value,
+        "metric_style_depth": metric_style,
+        "maximum_model_depth": payload.get("max_depth") if metric_style else None,
+        "calibrated_metric_truth": False,
+        "scale_policy": (
+            "metric_style_monocular_output_not_calibrated_truth"
+            if metric_style
+            else "relative_or_unknown_depth_scale"
+        ),
+    }, manifest_path
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--geometry-dir", required=True)
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--sample-id", default="single_mesh")
+    parser.add_argument("--category", default="stairs")
+    parser.add_argument("--frames", type=int, default=72)
+    parser.add_argument("--duration-ms", type=int, default=140)
+    parser.add_argument("--width", type=int, default=640)
+    parser.add_argument("--height", type=int, default=480)
+    parser.add_argument("--pitch", type=float, default=-25.0)
+    parser.add_argument("--stride", type=int, default=6)
+    parser.add_argument("--thickness-ratio", type=float, default=0.12)
+    parser.add_argument("--stair-cross-samples", type=int, default=48)
+    parser.add_argument("--stair-step-count", type=int, default=0)
+    parser.add_argument(
+        "--texture-image",
+        default=None,
+        help=(
+            "Optional frozen RGB texture. When supplied it is required and takes "
+            "strict precedence over every discovered completion/fallback image."
+        ),
+    )
+    parser.add_argument(
+        "--hidden-tint",
+        type=float,
+        default=0.0,
+        help="Hidden-region review tint in [0,1]. Default 0 preserves source texture.",
+    )
+    parser.add_argument(
+        "--include-depth-solid",
+        action="store_true",
+        help=(
+            "Also render the experimental depth-extruded solid. It is disabled by "
+            "default because long side-wall triangles are not publication quality."
+        ),
+    )
+    parser.add_argument(
+        "--model-only",
+        action="store_true",
+        help=(
+            "Build PLY/GLB presentation models without duplicate CPU GIFs; "
+            "use the dedicated GPU turntable renderer for final review media."
+        ),
+    )
+    return parser
+
+
+def main() -> int:
+    parser = build_argument_parser()
+    args = parser.parse_args()
+
+    geometry_dir = Path(args.geometry_dir).expanduser().resolve()
+    output_dir = Path(args.output_dir).expanduser().resolve()
+    texture_image = (
+        Path(args.texture_image).expanduser().resolve()
+        if args.texture_image
+        else None
+    )
+    required = [
+        geometry_dir / "completed_mesh.ply",
+        geometry_dir / "completed_depth.npy",
+        geometry_dir / "amodal_target_mask.png",
+    ]
+    if texture_image is not None:
+        required.append(texture_image)
+    missing = [str(path) for path in required if not path.is_file()]
+    if missing:
+        parser.error("missing geometry input(s): " + ", ".join(missing))
+    if args.frames < 12 or args.duration_ms < 20:
+        parser.error("use at least 12 frames and 20 ms per frame")
+    if not 0.0 <= args.hidden_tint <= 1.0:
+        parser.error("--hidden-tint must be in [0,1]")
+
+    depth = np.load(geometry_dir / "completed_depth.npy").astype(np.float32)
+    shape = depth.shape
+    target_mask = clean_target_mask(
+        read_mask(geometry_dir / "amodal_target_mask.png", shape),
+        close_kernel=5,
+        keep_largest=True,
+    )
+    visible_path = geometry_dir / "target_visible_mask.png"
+    visible_mask = read_mask(visible_path, shape) if visible_path.is_file() else None
+    colors, texture_source = prepare_texture(
+        geometry_dir.parent,
+        geometry_dir,
+        shape,
+        hidden_tint=args.hidden_tint,
+        texture_override=texture_image,
+    )
+    selected_texture_path = Path(texture_source.split(" + ", 1)[0]).resolve()
+    if (
+        texture_image is not None
+        and selected_texture_path != texture_image
+    ):
+        raise RuntimeError(
+            "Explicit --texture-image lost strict priority during texture selection"
+        )
+    geometry_manifest_path = geometry_dir / "geometry_manifest.json"
+    geometry_manifest = (
+        read_json(geometry_manifest_path)
+        if geometry_manifest_path.is_file()
+        else {}
+    )
+    depth_context, depth_manifest_path = load_depth_context(geometry_dir)
+    metric_style_depth = bool(depth_context["metric_style_depth"])
+    depth_manifest = (
+        read_json(depth_manifest_path)
+        if depth_manifest_path is not None
+        else {}
+    )
+    manifest_depth_output = resolve_declared_path(
+        depth_manifest.get("output_depth"),
+        depth_manifest_path.parent if depth_manifest_path is not None else geometry_dir,
+    )
+    geometry_depth_path = resolve_declared_path(
+        geometry_manifest.get("depth_source"),
+        geometry_manifest_path.parent,
+    )
+    depth_context["geometry_depth_source_matches_manifest"] = (
+        geometry_depth_path.resolve() == manifest_depth_output.resolve()
+        if geometry_depth_path is not None and manifest_depth_output is not None
+        else None
+    )
+    depth_context["manifest_output_depth_filename"] = (
+        manifest_depth_output.name
+        if manifest_depth_output is not None
+        else None
+    )
+    depth_context["geometry_depth_source_filename"] = (
+        geometry_depth_path.name
+        if geometry_depth_path is not None
+        else None
+    )
+    stair_edges, stair_edge_provenance = (
+        trusted_stair_edges_from_manifest(geometry_manifest)
+    )
+    stair_slope = float(geometry_manifest.get("stair_edge_slope", 0.0))
+    size = (args.width, args.height)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    variants: list[dict[str, Any]] = []
+    source_mesh_path = geometry_dir / "completed_mesh.ply"
+    source_vertices, source_colors, source_faces = load_ply(source_mesh_path)
+    variants.append(
+        save_variant(
+            output_dir,
+            "01_surface_faces",
+            "Original continuous triangle faces",
+            source_vertices,
+            source_colors,
+            source_faces,
+            sample_id=args.sample_id,
+            category=args.category,
+            frames=args.frames,
+            duration_ms=args.duration_ms,
+            size=size,
+            pitch=args.pitch,
+            source_ply=source_mesh_path,
+            render_outputs=not args.model_only,
+        )
+    )
+
+    if args.include_depth_solid:
+        if args.category == "stairs" and stair_edges:
+            solid_vertices, solid_colors, solid_faces, solid_metadata = build_continuous_stair_mesh(
+                depth,
+                colors,
+                target_mask,
+                stride=args.stride,
+                thickness=None,
+                thickness_ratio=args.thickness_ratio,
+                support_mode="stair_sidewall",
+                wedge_base_drop_ratio=0.12,
+                stair_edges_y=stair_edges,
+                stair_edge_slope=stair_slope,
+                cross_samples=args.stair_cross_samples,
+            )
+            solid_title = "Experimental depth-extruded stairs"
+        else:
+            solid_vertices, solid_colors, solid_faces, solid_metadata = build_solid_mesh(
+                depth,
+                colors,
+                target_mask,
+                stride=args.stride,
+                max_depth_jump=None,
+                thickness=None,
+                thickness_ratio=args.thickness_ratio,
+                support_mode="boundary",
+                wedge_base_drop_ratio=0.12,
+                category=args.category,
+                stair_edges_y=stair_edges,
+            )
+            solid_title = "Experimental depth-extruded surface"
+        solid_row = save_variant(
+            output_dir,
+            "debug_depth_solid",
+            solid_title,
+            solid_vertices,
+            solid_colors,
+            solid_faces,
+            sample_id=args.sample_id,
+            category=args.category,
+            frames=args.frames,
+            duration_ms=args.duration_ms,
+            size=size,
+            pitch=args.pitch,
+            render_outputs=not args.model_only,
+        )
+        solid_row["construction"] = solid_metadata
+        solid_row["publication_ready"] = False
+        variants.append(solid_row)
+
+    if args.category == "stairs":
+        (
+            canonical_vertices,
+            canonical_colors,
+            canonical_faces,
+            canonical_metadata,
+        ) = build_canonical_staircase_prism_mesh(
+            depth,
+            colors,
+            target_mask,
+            stride=args.stride,
+            thickness=None,
+            thickness_ratio=args.thickness_ratio,
+            stair_edges_y=stair_edges,
+            stair_edge_slope=stair_slope,
+            step_count=args.stair_step_count,
+            metric_style_depth=metric_style_depth,
+        )
+        canonical_row = save_variant(
+            output_dir,
+            "02_canonical_stairs",
+            "Depth-scaled textured open-world staircase",
+            canonical_vertices,
+            canonical_colors,
+            canonical_faces,
+            sample_id=args.sample_id,
+            category=args.category,
+            frames=args.frames,
+            duration_ms=args.duration_ms,
+            size=size,
+            pitch=args.pitch,
+            render_outputs=not args.model_only,
+        )
+        canonical_row["construction"] = canonical_metadata
+        canonical_row["publication_ready"] = True
+        variants.append(canonical_row)
+    elif args.category in CONTINUOUS_SURFACE_CATEGORIES:
+        presentation_mask, presentation_mask_metadata = (
+            continuous_presentation_mask(target_mask)
+        )
+        continuous_depth, surface_metadata = idealized_continuous_presentation_depth(
+            depth,
+            presentation_mask,
+            visible_mask,
+        )
+        presentation_depth_bounds = surface_metadata.get("depth_bounds", [0.0, 1.0])
+        presentation_depth_jump_limit = max(
+            1.0,
+            float(presentation_depth_bounds[1])
+            - float(presentation_depth_bounds[0])
+            + 1e-3,
+        )
+        (
+            support_vertices,
+            support_colors,
+            support_faces,
+            support_metadata,
+        ) = build_solid_mesh(
+            continuous_depth,
+            colors,
+            presentation_mask,
+            stride=args.stride,
+            max_depth_jump=presentation_depth_jump_limit,
+            thickness=None,
+            thickness_ratio=args.thickness_ratio,
+            support_mode="vertical_slab",
+            wedge_base_drop_ratio=0.12,
+            category=args.category,
+            stair_edges_y=None,
+        )
+        support_row = save_variant(
+            output_dir,
+            "02_continuous_support_surface",
+            "Category-constrained continuous support surface",
+            support_vertices,
+            support_colors,
+            support_faces,
+            sample_id=args.sample_id,
+            category=args.category,
+            frames=args.frames,
+            duration_ms=args.duration_ms,
+            size=size,
+            pitch=args.pitch,
+            render_outputs=not args.model_only,
+        )
+        support_row["construction"] = {
+            **support_metadata,
+            **surface_metadata,
+            "presentation_mask": presentation_mask_metadata,
+            "role": "nonmetric_category_constrained_geometry_hypothesis",
+            "safe_passage_claim": False,
+            "human_review_required": True,
+        }
+        support_row["publication_ready"] = True
+        variants.append(support_row)
+
+    contact_sheet = output_dir / "3d_variants_contact_sheet.jpg"
+    if not args.model_only:
+        build_contact_sheet(contact_sheet, variants)
+    texture_parts = texture_source.split(" + ")
+    portable_texture_source = " + ".join(
+        [portable_path(texture_parts[0], output_dir), *texture_parts[1:]]
+    )
+    selected_texture_record = portable_file_record(
+        selected_texture_path,
+        output_dir,
+    )
+    explicit_texture_record = (
+        portable_file_record(texture_image, output_dir)
+        if texture_image is not None
+        else None
+    )
+    if depth_manifest_path is not None:
+        depth_context["manifest"] = portable_path(depth_manifest_path, output_dir)
+    else:
+        depth_context["manifest"] = None
+    portable_variants = [
+        portable_variant_row(row, output_dir)
+        for row in variants
+    ]
+    canonical_construction = next(
+        (
+            row.get("construction", {})
+            for row in variants
+            if row.get("name") == "02_canonical_stairs"
+        ),
+        {},
+    )
+    manifest = {
+        "schema_version": "accessibilityamodal_3d_presentation_variants_v2",
+        "sample_id": args.sample_id,
+        "category": args.category,
+        "geometry_dir": portable_path(geometry_dir, output_dir),
+        "texture_source": portable_texture_source,
+        "texture": {
+            "selection_policy": (
+                "explicit_frozen_texture_strict_priority"
+                if texture_image is not None
+                else "pipeline_texture_discovery"
+            ),
+            "explicit_frozen_texture": explicit_texture_record,
+            "selected_texture": selected_texture_record,
+            "selected_source_description": portable_texture_source,
+            "hidden_tint": float(args.hidden_tint),
+            "source_file_modified": False,
+            "used_for_vertex_colors": True,
+        },
+        "geometry": {
+            "source_geometry_manifest": (
+                portable_path(geometry_manifest_path, output_dir)
+                if geometry_manifest_path.is_file()
+                else None
+            ),
+            "geometry_mode": geometry_manifest.get("geometry_mode"),
+            "depth": depth_context,
+            "metric_style_depth": metric_style_depth,
+            "calibrated_metric_truth": False,
+            "stair_edge_rows": stair_edges,
+            "stair_edge_provenance": stair_edge_provenance,
+            "stair_edge_source": (
+                geometry_manifest.get("stair_edge_source")
+                or geometry_manifest.get("edge_source")
+            ),
+            "stair_step_count": canonical_construction.get("stair_step_count"),
+            "stair_step_count_source": canonical_construction.get(
+                "stair_step_count_source"
+            ),
+            "role": "open_world_accessibility_surface_hypothesis",
+        },
+        "depth_model_identity": depth_context.get("model_identity"),
+        "metric_style_depth": metric_style_depth,
+        "frames": args.frames,
+        "duration_ms": args.duration_ms,
+        "seconds_per_rotation": round(args.frames * args.duration_ms / 1000.0, 3),
+        "contact_sheet": (
+            portable_path(contact_sheet, output_dir)
+            if not args.model_only
+            else None
+        ),
+        "model_only": bool(args.model_only),
+        "variants": portable_variants,
+        "publication_variants": [
+            row["name"] for row in variants if row.get("publication_ready", True)
+        ],
+        "experimental_depth_solid_included": args.include_depth_solid,
+        "depth_is_metric_ground_truth": False,
+        "solid_models_are_visual_geometry_hypotheses": True,
+        "open_world_semantics": {
+            "scene_role": "local_accessibility_surface_patch",
+            "freestanding_object_model": False,
+            "context_landings": canonical_construction.get("context_landings"),
+            "automatic_passability_claim": False,
+            "human_review_required": True,
+        },
+        "path_policy": "All filesystem paths are relative to manifest.json.",
+    }
+    (output_dir / "manifest.json").write_text(
+        json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8"
+    )
+    print(json.dumps(manifest, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/accessibility_amodal_mask.py

@@ -0,0 +1,265 @@
+#!/usr/bin/env python3
+"""Predict review-only hidden/amodal masks for one accessibility image.
+
+The tiny adapter consumes RGB, a visible-target proposal, an obstacle proposal,
+and a coarse stairs/non-stairs category plane. Predictions are constrained to
+the obstacle support and written as candidates, never as ground truth.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+import torch
+from PIL import Image, ImageOps
+
+
+TOOLS_DIR = Path(__file__).resolve().parent
+if str(TOOLS_DIR) not in sys.path:
+    sys.path.insert(0, str(TOOLS_DIR))
+
+import train_accessibility_amodal_adapter as trainer  # noqa: E402
+
+
+CATEGORIES = ("curb_cut", "ramp", "stairs", "tactile_paving", "walkway")
+
+
+def load_rgb(path: Path) -> Image.Image:
+    return ImageOps.exif_transpose(Image.open(path)).convert("RGB")
+
+
+def load_mask(path: Path, size: tuple[int, int]) -> np.ndarray:
+    image = ImageOps.exif_transpose(Image.open(path)).convert("L")
+    if image.size != size:
+        raise ValueError(
+            f"Mask/RGB raster mismatch for {path}: mask={image.size}, rgb={size}. "
+            "Refusing to resize because this can hide EXIF-orientation misalignment."
+        )
+    return np.asarray(image) > 127
+
+
+def save_mask(path: Path, mask: np.ndarray) -> None:
+    Image.fromarray(mask.astype(np.uint8) * 255, mode="L").save(path)
+
+
+def retain_hidden_components(obstacle: np.ndarray, hidden: np.ndarray) -> np.ndarray:
+    if not hidden.any():
+        return np.zeros_like(obstacle)
+    _, labels = cv2.connectedComponents(obstacle.astype(np.uint8), connectivity=8)
+    keep = np.unique(labels[obstacle & hidden])
+    keep = keep[keep != 0]
+    return np.isin(labels, keep)
+
+
+def checkpoint_category_names(checkpoint: dict[str, Any], model_input_channels: int) -> tuple[str, ...]:
+    """Recover the category-plane order used to train a checkpoint.
+
+    The original adapter used only ``stairs`` and ``walkway`` category planes
+    (7 total input channels).  The current adapter uses one plane for each
+    canonical category (10 total).  Keeping this explicit makes old reviewed
+    runs reproducible while preventing a silent channel-order mismatch.
+    """
+    category_count = model_input_channels - 5  # RGB + visible + obstacle
+    if category_count < 0:
+        raise ValueError(
+            f"Checkpoint expects {model_input_channels} inputs; at least 5 are required."
+        )
+    recorded = checkpoint.get("input_channels", [])
+    if isinstance(recorded, list):
+        names = tuple(name for name in recorded if name in CATEGORIES)
+        if len(names) == category_count:
+            return names
+    if category_count == len(CATEGORIES):
+        return CATEGORIES
+    raise ValueError(
+        "Checkpoint category-plane metadata is incompatible with its model input shape: "
+        f"expected {category_count} category planes, recorded={recorded!r}."
+    )
+
+
+def category_planes(category: str, names: tuple[str, ...], size: int) -> np.ndarray:
+    return np.stack(
+        [np.full((size, size), category == name, dtype=np.float32) for name in names],
+        axis=0,
+    )
+
+
+def predict_probability(
+    model: torch.nn.Module,
+    device: torch.device,
+    image: Image.Image,
+    visible: np.ndarray,
+    obstacle: np.ndarray,
+    category: str,
+    category_names: tuple[str, ...],
+    image_size: int,
+) -> np.ndarray:
+    rgb = np.asarray(
+        image.resize((image_size, image_size), Image.Resampling.BILINEAR),
+        dtype=np.float32,
+    ) / 255.0
+    visible_small = np.asarray(
+        Image.fromarray(visible.astype(np.uint8) * 255).resize(
+            (image_size, image_size), Image.Resampling.NEAREST
+        )
+    ) > 127
+    obstacle_small = np.asarray(
+        Image.fromarray(obstacle.astype(np.uint8) * 255).resize(
+            (image_size, image_size), Image.Resampling.NEAREST
+        )
+    ) > 127
+    inputs = np.concatenate(
+        [
+            rgb.transpose(2, 0, 1),
+            visible_small[None].astype(np.float32),
+            obstacle_small[None].astype(np.float32),
+            category_planes(category, category_names, image_size),
+        ],
+        axis=0,
+    )
+    with torch.inference_mode():
+        logits = model(torch.from_numpy(inputs[None]).to(device)).sigmoid()[0, 0]
+    probability = np.asarray(
+        Image.fromarray(logits.detach().cpu().numpy().astype(np.float32), mode="F").resize(
+            image.size, Image.Resampling.BILINEAR
+        )
+    ).copy()
+    probability *= (obstacle & ~visible).astype(np.float32)
+    return probability
+
+
+def overlay(
+    image: Image.Image,
+    visible: np.ndarray,
+    hidden: np.ndarray,
+    obstacle: np.ndarray,
+) -> Image.Image:
+    result = np.asarray(image, dtype=np.float32).copy()
+    for mask, color, alpha in (
+        (visible, np.asarray((30, 210, 70), dtype=np.float32), 0.42),
+        (hidden, np.asarray((40, 100, 245), dtype=np.float32), 0.62),
+        (obstacle, np.asarray((230, 45, 45), dtype=np.float32), 0.52),
+    ):
+        result[mask] = result[mask] * (1.0 - alpha) + color * alpha
+    return Image.fromarray(np.clip(result, 0, 255).astype(np.uint8), mode="RGB")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--image", type=Path, required=True)
+    parser.add_argument("--target-visible-mask", type=Path, required=True)
+    parser.add_argument("--obstacle-candidate-mask", type=Path, required=True)
+    parser.add_argument("--category", choices=CATEGORIES, required=True)
+    parser.add_argument("--checkpoint", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument("--image-size", type=int, default=256)
+    parser.add_argument(
+        "--threshold",
+        type=float,
+        default=None,
+        help="Defaults to validation_threshold stored in the checkpoint.",
+    )
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    image_path = args.image.expanduser().resolve()
+    checkpoint_path = args.checkpoint.expanduser().resolve()
+    output_dir = args.output_dir.expanduser().resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    image = load_rgb(image_path)
+    visible = load_mask(args.target_visible_mask.expanduser().resolve(), image.size)
+    obstacle_candidate = load_mask(
+        args.obstacle_candidate_mask.expanduser().resolve(), image.size
+    )
+    visible &= ~obstacle_candidate
+
+    device = torch.device(args.device)
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA requested but unavailable; run through Slurm or use --device cpu")
+    checkpoint: dict[str, Any] = torch.load(
+        checkpoint_path, map_location=device, weights_only=False
+    )
+    model_state = checkpoint.get("model_state")
+    if not isinstance(model_state, dict) or "enc1.block.0.weight" not in model_state:
+        raise ValueError("Checkpoint does not contain a TinyAmodalUNet model_state.")
+    model_input_channels = int(model_state["enc1.block.0.weight"].shape[1])
+    category_names = checkpoint_category_names(checkpoint, model_input_channels)
+    threshold = float(
+        args.threshold
+        if args.threshold is not None
+        else checkpoint.get("validation_threshold", 0.6)
+    )
+    model = trainer.TinyAmodalUNet(in_channels=model_input_channels).to(device)
+    model.load_state_dict(model_state)
+    model.eval()
+
+    probability = predict_probability(
+        model,
+        device,
+        image,
+        visible,
+        obstacle_candidate,
+        args.category,
+        category_names,
+        args.image_size,
+    )
+    hidden = probability >= threshold
+    obstacle = retain_hidden_components(obstacle_candidate & ~visible, hidden)
+    hidden &= obstacle
+    amodal = visible | hidden
+
+    if np.any(visible & obstacle):
+        raise AssertionError("target_visible overlaps obstacle")
+    if np.any(hidden & ~obstacle):
+        raise AssertionError("hidden lies outside obstacle")
+    if np.any(hidden != (amodal & ~visible)):
+        raise AssertionError("hidden formula failed")
+
+    save_mask(output_dir / "target_visible.png", visible)
+    save_mask(output_dir / "obstacle_all_detected.png", obstacle_candidate)
+    save_mask(output_dir / "obstacle.png", obstacle)
+    save_mask(output_dir / "hidden.png", hidden)
+    save_mask(output_dir / "target_amodal.png", amodal)
+    Image.fromarray(
+        np.clip(probability * 255.0, 0, 255).astype(np.uint8), mode="L"
+    ).save(output_dir / "hidden_probability.png")
+    overlay(image, visible, hidden, obstacle).save(output_dir / "mask_overlay.png")
+
+    metadata = {
+        "image": str(image_path),
+        "raster_orientation_policy": "RGB and every input mask are decoded with PIL ImageOps.exif_transpose and must match exactly.",
+        "display_raster_size": {"width": image.width, "height": image.height},
+        "category": args.category,
+        "checkpoint": str(checkpoint_path),
+        "model_input_channels": model_input_channels,
+        "category_plane_names": list(category_names),
+        "threshold": threshold,
+        "target_visible_pixels": int(visible.sum()),
+        "obstacle_candidate_pixels": int(obstacle_candidate.sum()),
+        "obstacle_pixels": int(obstacle.sum()),
+        "hidden_pixels": int(hidden.sum()),
+        "target_amodal_pixels": int(amodal.sum()),
+        "automatic_masks_are_ground_truth": False,
+        "review_status": "single_image_candidate_requires_human_review",
+        "mask_invariants_passed": True,
+    }
+    (output_dir / "metadata.json").write_text(
+        json.dumps(metadata, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps(metadata, ensure_ascii=False, indent=2, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/accessibility_fast_2d_baseline.py

@@ -0,0 +1,581 @@
+#!/usr/bin/env python3
+"""Run the optional fast CPU 2D baseline on accessibility samples.
+
+The script is intentionally non-destructive: it only reads dataset samples and
+writes a mirrored result tree under --output-dir.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import random
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+from PIL import Image, ImageDraw, ImageOps
+
+try:
+    from tools.accessibility_dataset_layout import iter_sample_dirs, resolve_sample_dir
+except ModuleNotFoundError:  # Direct execution from tools/
+    from accessibility_dataset_layout import iter_sample_dirs, resolve_sample_dir
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+IMAGE_CANDIDATES = ("image.jpg", "image.jpeg", "image.png")
+
+
+@dataclass(frozen=True)
+class Sample:
+    sample_id: str
+    sample_dir: Path
+    image_path: Path
+    metadata: dict[str, Any]
+    target_visible_path: Path | None = None
+    target_amodal_path: Path | None = None
+    hidden_path: Path | None = None
+    obstacle_path: Path | None = None
+
+
+def resolve_path(path: str | Path) -> Path:
+    candidate = Path(path)
+    if candidate.is_absolute():
+        return candidate
+    return PROJECT_ROOT / candidate
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def read_rgb(path: Path) -> np.ndarray:
+    return np.array(ImageOps.exif_transpose(Image.open(path)).convert("RGB"))
+
+
+def read_mask(path: Path | None, shape: tuple[int, int]) -> np.ndarray | None:
+    if path is None or not path.is_file():
+        return None
+    mask = np.array(ImageOps.exif_transpose(Image.open(path)).convert("L")) > 127
+    h, w = shape
+    if mask.shape != (h, w):
+        raise ValueError(
+            f"Mask/RGB raster mismatch for {path}: mask={mask.shape}, rgb={(h, w)}. "
+            "Refusing to resize because this can hide EXIF-orientation misalignment."
+        )
+    return mask.astype(bool)
+
+
+def save_mask(path: Path, mask: np.ndarray) -> None:
+    Image.fromarray(mask.astype(np.uint8) * 255).save(path)
+
+
+def save_rgb(path: Path, image: np.ndarray) -> None:
+    Image.fromarray(np.clip(image, 0, 255).astype(np.uint8), mode="RGB").save(path)
+
+
+def maybe_path(sample_dir: Path, name: str) -> Path | None:
+    path = sample_dir / name
+    return path if path.is_file() else None
+
+
+def find_image_path(sample_dir: Path, metadata: dict[str, Any], dataset_root: Path) -> Path:
+    image_file = metadata.get("image_file")
+    if isinstance(image_file, str):
+        candidates = [
+            sample_dir / Path(image_file).name,
+            dataset_root / image_file,
+            PROJECT_ROOT / image_file,
+        ]
+        for candidate in candidates:
+            if candidate.is_file():
+                return candidate
+    for name in IMAGE_CANDIDATES:
+        candidate = sample_dir / name
+        if candidate.is_file():
+            return candidate
+    raise FileNotFoundError(f"No image file found in {sample_dir}")
+
+
+def sample_from_dir(sample_dir: Path, dataset_root: Path) -> Sample:
+    metadata_path = sample_dir / "metadata.json"
+    metadata = read_json(metadata_path) if metadata_path.is_file() else {}
+    sample_id = str(metadata.get("sample_id") or sample_dir.name)
+    return Sample(
+        sample_id=sample_id,
+        sample_dir=sample_dir,
+        image_path=find_image_path(sample_dir, metadata, dataset_root),
+        metadata=metadata,
+        target_visible_path=maybe_path(sample_dir, "target_visible.png"),
+        target_amodal_path=maybe_path(sample_dir, "target_amodal.png"),
+        hidden_path=maybe_path(sample_dir, "hidden.png"),
+        obstacle_path=maybe_path(sample_dir, "obstacle.png"),
+    )
+
+
+def discover_samples(
+    dataset_root: Path,
+    sample_ids: list[str],
+    categories: set[str],
+    splits: set[str],
+) -> list[Sample]:
+    sample_root = dataset_root / "samples" if (dataset_root / "samples").is_dir() else dataset_root
+    if sample_ids:
+        dirs = [resolve_sample_dir(sample_root, sample_id) for sample_id in sample_ids]
+    else:
+        dirs = list(iter_sample_dirs(sample_root))
+
+    samples: list[Sample] = []
+    for sample_dir in dirs:
+        if not sample_dir.is_dir():
+            raise FileNotFoundError(f"Missing sample directory: {sample_dir}")
+        sample = sample_from_dir(sample_dir, dataset_root)
+        category = str(sample.metadata.get("category") or sample.metadata.get("taxonomy_category") or "")
+        split = str(sample.metadata.get("split") or sample.metadata.get("strict_gt_split") or "")
+        if categories and category not in categories:
+            continue
+        if splits and split not in splits:
+            continue
+        samples.append(sample)
+    return samples
+
+
+def hidden_pixel_count(sample: Sample) -> int:
+    value = sample.metadata.get("hidden_pixels")
+    if isinstance(value, int):
+        return value
+    if sample.hidden_path and sample.hidden_path.is_file():
+        return int((np.array(Image.open(sample.hidden_path).convert("L")) > 127).sum())
+    return 0
+
+
+def choose_samples(samples: list[Sample], args: argparse.Namespace) -> list[Sample]:
+    eligible = [sample for sample in samples if hidden_pixel_count(sample) >= args.min_hidden_pixels]
+    if args.sample_policy == "largest-hidden":
+        eligible.sort(key=lambda sample: (-hidden_pixel_count(sample), sample.sample_id))
+    elif args.sample_policy == "random":
+        rng = random.Random(args.seed)
+        rng.shuffle(eligible)
+    else:
+        eligible.sort(key=lambda sample: sample.sample_id)
+
+    if args.all:
+        return eligible
+    return eligible[: args.limit]
+
+
+def ellipse_kernel(radius: int) -> np.ndarray | None:
+    if radius <= 0:
+        return None
+    size = radius * 2 + 1
+    return cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (size, size))
+
+
+def dilate_mask(mask: np.ndarray, radius: int) -> np.ndarray:
+    kernel = ellipse_kernel(radius)
+    if kernel is None or not mask.any():
+        return mask.astype(bool)
+    return cv2.dilate(mask.astype(np.uint8), kernel, iterations=1).astype(bool)
+
+
+def close_mask(mask: np.ndarray, radius: int) -> np.ndarray:
+    kernel = ellipse_kernel(radius)
+    if kernel is None or not mask.any():
+        return mask.astype(bool)
+    return cv2.morphologyEx(mask.astype(np.uint8), cv2.MORPH_CLOSE, kernel).astype(bool)
+
+
+def derive_hidden_mask(
+    hidden: np.ndarray | None,
+    target_visible: np.ndarray | None,
+    target_amodal: np.ndarray | None,
+) -> tuple[np.ndarray, str]:
+    if hidden is not None and hidden.any():
+        derived = hidden.astype(bool).copy()
+        source = "hidden mask"
+        if target_visible is not None and target_amodal is not None:
+            derived |= target_amodal & ~target_visible
+            source += " union target_amodal-minus-target_visible"
+        return derived, source
+    if target_visible is not None and target_amodal is not None:
+        return (target_amodal & ~target_visible).astype(bool), "target_amodal-minus-target_visible"
+    if target_amodal is not None:
+        return target_amodal.astype(bool), "target_amodal fallback"
+    raise ValueError("Need hidden.png or target_amodal.png + target_visible.png to derive completion mask")
+
+
+def build_inpaint_mask(
+    hidden: np.ndarray,
+    target_visible: np.ndarray | None,
+    target_amodal: np.ndarray | None,
+    obstacle: np.ndarray | None,
+    mode: str,
+    target_band_dilate: int,
+    final_dilate: int,
+    close_radius: int,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    mask = hidden.astype(bool).copy()
+    metadata: dict[str, Any] = {
+        "mode": mode,
+        "hidden_pixels": int(hidden.sum()),
+        "added_obstacle_pixels": 0,
+    }
+
+    if mode == "hidden":
+        pass
+    elif mode == "hidden_dilated":
+        mask = dilate_mask(mask, target_band_dilate)
+    elif mode == "target_occluder":
+        if obstacle is not None:
+            obstacle_on_target = obstacle & dilate_mask(hidden, target_band_dilate)
+            metadata["added_obstacle_pixels"] = int((obstacle_on_target & ~mask).sum())
+            mask |= obstacle_on_target
+    elif mode == "obstacle":
+        if obstacle is not None:
+            metadata["added_obstacle_pixels"] = int((obstacle & ~mask).sum())
+            mask |= obstacle
+    else:
+        raise ValueError(f"Unsupported mask mode: {mode}")
+
+    mask = close_mask(mask, close_radius)
+    mask = dilate_mask(mask, final_dilate)
+    metadata["final_pixels"] = int(mask.sum())
+    return mask.astype(bool), metadata
+
+
+def inpaint_opencv(rgb: np.ndarray, mask: np.ndarray, radius: float, method: str) -> np.ndarray:
+    if not mask.any():
+        return rgb.copy()
+    flag = cv2.INPAINT_TELEA if method == "telea" else cv2.INPAINT_NS
+    bgr = cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR)
+    completed = cv2.inpaint(bgr, mask.astype(np.uint8) * 255, radius, flag)
+    return cv2.cvtColor(completed, cv2.COLOR_BGR2RGB)
+
+
+def inpaint_opencv_pyramid(
+    rgb: np.ndarray,
+    mask: np.ndarray,
+    radius: float,
+    method: str,
+    levels: int,
+    seam_radius: int,
+) -> np.ndarray:
+    if not mask.any() or levels <= 1:
+        return inpaint_opencv(rgb, mask, radius, method)
+
+    h, w = rgb.shape[:2]
+    scale = 1.0 / float(2 ** (levels - 1))
+    low_w = max(32, int(round(w * scale)))
+    low_h = max(32, int(round(h * scale)))
+    low_rgb = cv2.resize(rgb, (low_w, low_h), interpolation=cv2.INTER_AREA)
+    low_mask = cv2.resize(mask.astype(np.uint8), (low_w, low_h), interpolation=cv2.INTER_NEAREST) > 0
+    low_completed = inpaint_opencv(low_rgb, low_mask, radius, method)
+    up_completed = cv2.resize(low_completed, (w, h), interpolation=cv2.INTER_CUBIC)
+
+    composite = rgb.copy()
+    composite[mask] = up_completed[mask]
+
+    seam = dilate_mask(mask, seam_radius)
+    inner = cv2.erode(
+        mask.astype(np.uint8),
+        ellipse_kernel(max(1, seam_radius // 2)),
+        iterations=1,
+    ).astype(bool)
+    seam = seam & ~inner
+    if seam.any():
+        composite = inpaint_opencv(composite, seam, max(1.0, radius * 0.5), method)
+    return composite
+
+
+def run_inpaint(rgb: np.ndarray, mask: np.ndarray, args: argparse.Namespace) -> np.ndarray:
+    if args.opencv_mode == "pyramid":
+        return inpaint_opencv_pyramid(
+            rgb,
+            mask,
+            args.inpaint_radius,
+            args.method,
+            args.pyramid_levels,
+            args.seam_radius,
+        )
+    return inpaint_opencv(rgb, mask, args.inpaint_radius, args.method)
+
+
+def blend_masks(rgb: np.ndarray, masks: list[tuple[np.ndarray, tuple[int, int, int], float]]) -> np.ndarray:
+    out = rgb.astype(np.float32).copy()
+    for mask, color, alpha in masks:
+        if mask is not None and mask.any():
+            out[mask] = out[mask] * (1.0 - alpha) + np.array(color, dtype=np.float32) * alpha
+    return np.clip(out, 0, 255).astype(np.uint8)
+
+
+def write_target_rgba(path: Path, completed: np.ndarray, target_amodal: np.ndarray | None, inpaint_mask: np.ndarray) -> None:
+    alpha = target_amodal if target_amodal is not None and target_amodal.any() else inpaint_mask
+    rgba = np.dstack([completed, alpha.astype(np.uint8) * 255])
+    Image.fromarray(rgba, mode="RGBA").save(path)
+
+
+def checkerboard(size: tuple[int, int], cell: int = 16) -> Image.Image:
+    width, height = size
+    yy, xx = np.indices((height, width))
+    pattern = ((xx // cell + yy // cell) % 2).astype(np.uint8)
+    values = np.where(pattern[..., None] == 0, 228, 188).astype(np.uint8)
+    image = np.repeat(values, 3, axis=2)
+    return Image.fromarray(image, mode="RGB")
+
+
+def rgba_on_checker(rgba_path: Path, size: tuple[int, int]) -> Image.Image:
+    image = Image.open(rgba_path).convert("RGBA")
+    canvas = checkerboard(image.size)
+    canvas.paste(image, (0, 0), image)
+    return ImageOps.contain(canvas, size)
+
+
+def label_panel(image: Image.Image, label: str, size: tuple[int, int]) -> Image.Image:
+    body = ImageOps.contain(image.convert("RGB"), size)
+    panel = Image.new("RGB", (size[0], size[1] + 28), "white")
+    draw = ImageDraw.Draw(panel)
+    draw.text((8, 8), label, fill=(0, 0, 0))
+    panel.paste(body, ((size[0] - body.width) // 2, 28 + (size[1] - body.height) // 2))
+    return panel
+
+
+def write_contact_sheet(
+    path: Path,
+    original: np.ndarray,
+    overlay: np.ndarray,
+    completed: np.ndarray,
+    rgba_path: Path,
+    panel_width: int,
+) -> None:
+    h, w = original.shape[:2]
+    panel_height = max(160, int(panel_width * h / max(w, 1)))
+    size = (panel_width, panel_height)
+    panels = [
+        label_panel(Image.fromarray(original), "source image", size),
+        label_panel(Image.fromarray(overlay), "mask guide", size),
+        label_panel(Image.fromarray(completed), "completed RGB", size),
+        label_panel(rgba_on_checker(rgba_path, size), "amodal target RGBA", size),
+    ]
+    sheet = Image.new("RGB", (sum(panel.width for panel in panels), max(panel.height for panel in panels)), "white")
+    x = 0
+    for panel in panels:
+        sheet.paste(panel, (x, 0))
+        x += panel.width
+    sheet.save(path, quality=92)
+
+
+def path_for_manifest(path: Path) -> str:
+    try:
+        return str(path.relative_to(PROJECT_ROOT))
+    except ValueError:
+        return str(path)
+
+
+def process_sample(sample: Sample, output_dir: Path, args: argparse.Namespace) -> dict[str, Any]:
+    sample_out = output_dir / sample.sample_id
+    if sample_out.exists() and not args.overwrite:
+        return {
+            "sample_id": sample.sample_id,
+            "status": "skipped_existing_output",
+            "output_dir": path_for_manifest(sample_out),
+        }
+    sample_out.mkdir(parents=True, exist_ok=True)
+
+    rgb = read_rgb(sample.image_path)
+    shape = rgb.shape[:2]
+    target_visible = read_mask(sample.target_visible_path, shape)
+    target_amodal = read_mask(sample.target_amodal_path, shape)
+    hidden_input = read_mask(sample.hidden_path, shape)
+    obstacle = read_mask(sample.obstacle_path, shape)
+    hidden, hidden_source = derive_hidden_mask(hidden_input, target_visible, target_amodal)
+    inpaint_mask, mask_meta = build_inpaint_mask(
+        hidden=hidden,
+        target_visible=target_visible,
+        target_amodal=target_amodal,
+        obstacle=obstacle,
+        mode=args.mask_mode,
+        target_band_dilate=args.target_band_dilate,
+        final_dilate=args.mask_dilate,
+        close_radius=args.mask_close,
+    )
+
+    mask_ratio = float(inpaint_mask.sum()) / float(inpaint_mask.size)
+    row: dict[str, Any] = {
+        "sample_id": sample.sample_id,
+        "category": sample.metadata.get("category") or sample.metadata.get("taxonomy_category"),
+        "split": sample.metadata.get("split") or sample.metadata.get("strict_gt_split"),
+        "source_image": path_for_manifest(sample.image_path),
+        "source_sample_dir": path_for_manifest(sample.sample_dir),
+        "hidden_source": hidden_source,
+        "mask": {
+            **mask_meta,
+            "mask_ratio": mask_ratio,
+            "max_mask_area_ratio": args.max_mask_area_ratio,
+        },
+        "backend": {
+            "name": "opencv",
+            "method": args.method,
+            "opencv_mode": args.opencv_mode,
+            "inpaint_radius": args.inpaint_radius,
+            "pyramid_levels": args.pyramid_levels,
+            "seam_radius": args.seam_radius,
+        },
+    }
+    if not inpaint_mask.any():
+        row["status"] = "skipped_empty_mask"
+        (sample_out / "sample_manifest.json").write_text(json.dumps(row, indent=2, ensure_ascii=False), encoding="utf-8")
+        return row
+    if mask_ratio > args.max_mask_area_ratio and not args.allow_large_mask:
+        save_mask(sample_out / "inpaint_mask.png", inpaint_mask)
+        row["status"] = "skipped_large_mask"
+        (sample_out / "sample_manifest.json").write_text(json.dumps(row, indent=2, ensure_ascii=False), encoding="utf-8")
+        return row
+
+    completed = run_inpaint(rgb, inpaint_mask, args)
+    mask_overlay = blend_masks(
+        rgb,
+        [
+            (target_amodal if target_amodal is not None else np.zeros(shape, dtype=bool), (0, 150, 255), 0.28),
+            (target_visible if target_visible is not None else np.zeros(shape, dtype=bool), (0, 220, 80), 0.42),
+            (inpaint_mask, (255, 48, 48), 0.65),
+        ],
+    )
+    completion_delta = np.abs(completed.astype(np.int16) - rgb.astype(np.int16)).max(axis=2) > 8
+
+    outputs = {
+        "completed_rgb": sample_out / "completed_rgb.png",
+        "amodal_target_rgba": sample_out / "amodal_target_rgba.png",
+        "inpaint_mask": sample_out / "inpaint_mask.png",
+        "hidden_mask": sample_out / "hidden_mask.png",
+        "mask_overlay": sample_out / "mask_overlay.jpg",
+        "completion_delta": sample_out / "completion_delta.png",
+        "contact_sheet": sample_out / "contact_sheet.jpg",
+        "manifest": sample_out / "sample_manifest.json",
+    }
+    save_rgb(outputs["completed_rgb"], completed)
+    write_target_rgba(outputs["amodal_target_rgba"], completed, target_amodal, inpaint_mask)
+    save_mask(outputs["inpaint_mask"], inpaint_mask)
+    save_mask(outputs["hidden_mask"], hidden)
+    save_rgb(outputs["mask_overlay"], mask_overlay)
+    save_mask(outputs["completion_delta"], completion_delta)
+    write_contact_sheet(
+        outputs["contact_sheet"],
+        rgb,
+        mask_overlay,
+        completed,
+        outputs["amodal_target_rgba"],
+        args.panel_width,
+    )
+
+    row["status"] = "completed"
+    row["outputs"] = {key: path_for_manifest(value) for key, value in outputs.items() if key != "manifest"}
+    outputs["manifest"].write_text(json.dumps(row, indent=2, ensure_ascii=False), encoding="utf-8")
+    return row
+
+
+def sample_from_single_image(args: argparse.Namespace) -> Sample:
+    image_path = resolve_path(args.image)
+    if not image_path.is_file():
+        raise FileNotFoundError(image_path)
+    sample_id = args.single_sample_id or image_path.stem
+    return Sample(
+        sample_id=sample_id,
+        sample_dir=image_path.parent,
+        image_path=image_path,
+        metadata={"sample_id": sample_id, "source": "single_image_cli"},
+        target_visible_path=resolve_path(args.target_visible_mask) if args.target_visible_mask else None,
+        target_amodal_path=resolve_path(args.target_amodal_mask) if args.target_amodal_mask else None,
+        hidden_path=resolve_path(args.hidden_mask) if args.hidden_mask else None,
+        obstacle_path=resolve_path(args.obstacle_mask) if args.obstacle_mask else None,
+    )
+
+
+def write_run_manifest(output_dir: Path, rows: list[dict[str, Any]], args: argparse.Namespace) -> None:
+    manifest = {
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "tool": "tools/accessibility_fast_2d_baseline.py",
+        "non_destructive_policy": "Read source samples only; write all derived RGB/RGBA outputs under output_dir.",
+        "output_dir": path_for_manifest(output_dir),
+        "args": {
+            "dataset_root": args.dataset_root,
+            "sample_id": args.sample_id,
+            "image": args.image,
+            "limit": args.limit,
+            "all": args.all,
+            "sample_policy": args.sample_policy,
+            "mask_mode": args.mask_mode,
+            "method": args.method,
+        },
+        "references": {
+            "saraao_amodal": "https://github.com/saraao/amodal",
+            "pix2gestalt": "https://github.com/cvlab-columbia/pix2gestalt",
+            "amodal_completion_in_the_wild": "https://github.com/Championchess/Amodal-Completion-in-the-Wild",
+            "local_amodal": "external backend; path supplied by user",
+            "local_pix2gestalt": "external backend; path supplied by user",
+            "local_amodal_wild": "external backend; path supplied by user",
+        },
+        "samples": rows,
+    }
+    (output_dir / "run_manifest.json").write_text(json.dumps(manifest, indent=2, ensure_ascii=False), encoding="utf-8")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--dataset-root", default="output/Accessibility", help="Dataset root containing samples/<sample_id>/ directories.")
+    parser.add_argument("--sample-id", action="append", default=[], help="Specific sample id to process. Repeat for multiple samples.")
+    parser.add_argument("--category", action="append", default=[], help="Optional category filter, e.g. stairs or ramp.")
+    parser.add_argument("--split", action="append", default=[], help="Optional split filter.")
+    parser.add_argument("--limit", type=int, default=8, help="Maximum samples when --all is not set.")
+    parser.add_argument("--all", action="store_true", help="Process all eligible samples.")
+    parser.add_argument("--sample-policy", choices=["largest-hidden", "random", "sorted"], default="largest-hidden")
+    parser.add_argument("--seed", type=int, default=13)
+    parser.add_argument("--min-hidden-pixels", type=int, default=32)
+
+    parser.add_argument("--image", default=None, help="Single-image mode input image.")
+    parser.add_argument("--single-sample-id", default=None)
+    parser.add_argument("--target-visible-mask", default=None)
+    parser.add_argument("--target-amodal-mask", default=None)
+    parser.add_argument("--hidden-mask", default=None)
+    parser.add_argument("--obstacle-mask", default=None)
+
+    parser.add_argument("--output-dir", default="output/amodal2d_color_completion")
+    parser.add_argument("--overwrite", action="store_true", help="Overwrite only files inside --output-dir.")
+    parser.add_argument("--mask-mode", choices=["hidden", "hidden_dilated", "target_occluder", "obstacle"], default="hidden")
+    parser.add_argument("--target-band-dilate", type=int, default=16, help="Pixels to dilate hidden completion support before intersecting obstacle mask.")
+    parser.add_argument("--mask-dilate", type=int, default=3, help="Final dilation radius for the inpaint mask.")
+    parser.add_argument("--mask-close", type=int, default=3, help="Closing radius for small holes in the inpaint mask.")
+    parser.add_argument("--max-mask-area-ratio", type=float, default=0.18, help="Skip unexpectedly huge masks unless --allow-large-mask is set.")
+    parser.add_argument("--allow-large-mask", action="store_true")
+    parser.add_argument("--opencv-mode", choices=["single", "pyramid"], default="single")
+    parser.add_argument("--pyramid-levels", type=int, default=3, help="Coarse-to-full resolution levels used with --opencv-mode pyramid.")
+    parser.add_argument("--seam-radius", type=int, default=8, help="Boundary refinement radius used with --opencv-mode pyramid.")
+    parser.add_argument("--method", choices=["telea", "ns"], default="telea", help="OpenCV inpainting method.")
+    parser.add_argument("--inpaint-radius", type=float, default=5.0)
+    parser.add_argument("--panel-width", type=int, default=420)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    output_dir = resolve_path(args.output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    if args.image:
+        samples = [sample_from_single_image(args)]
+    else:
+        dataset_root = resolve_path(args.dataset_root)
+        samples = discover_samples(dataset_root, args.sample_id, set(args.category), set(args.split))
+        samples = choose_samples(samples, args)
+
+    rows = [process_sample(sample, output_dir, args) for sample in samples]
+    write_run_manifest(output_dir, rows, args)
+    completed = sum(1 for row in rows if row.get("status") == "completed")
+    print(f"Wrote {completed}/{len(rows)} completed samples to {output_dir}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/accessibility_mask_proposals.py

@@ -0,0 +1,1332 @@
+#!/usr/bin/env python3
+"""Run prompt-consensus accessibility masks on a small reviewed pilot set.
+
+Supported backends:
+  sam3          Meta SAM 3 text-prompt concept segmentation (preferred)
+  grounded_sam  GroundingDINO boxes refined by SAM ViT-H (local control)
+
+The tool saves per-prompt masks, a high-recall union, a majority-vote core, an
+uncertainty mask, both raw/high-recall and filtered obstacle masks, overlays,
+and machine-readable quality scores.  Automatic output is a review proposal,
+never ground truth.
+"""
+
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import math
+import os
+import re
+import sys
+import traceback
+from collections import Counter
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    rows: list[dict[str, Any]] = []
+    with path.open("r", encoding="utf-8") as handle:
+        for line in handle:
+            if line.strip():
+                rows.append(json.loads(line))
+    return rows
+
+
+def write_jsonl(path: Path, rows: list[dict[str, Any]]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    with tmp_path.open("w", encoding="utf-8") as handle:
+        for row in rows:
+            handle.write(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n")
+    tmp_path.replace(path)
+
+
+def json_dump(path: Path, value: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    with tmp_path.open("w", encoding="utf-8") as handle:
+        json.dump(value, handle, ensure_ascii=False, indent=2, sort_keys=True)
+    tmp_path.replace(path)
+
+
+STANDARD_SAMPLE_OUTPUTS = (
+    "target_visible_candidate.png",
+    "target_visible_core.png",
+    "target_uncertain.png",
+    "obstacle_unfiltered_evidence.png",
+    "obstacle_all_detected.png",
+    "obstacle.png",
+    "obstacle_red.png",
+    "overlay.png",
+    "quality.json",
+)
+OBSTACLE_EVIDENCE_POLICY_VERSION = 1
+
+
+def load_resume_quality(sample_dir: Path, sample_id: str, backend_name: str) -> dict[str, Any] | None:
+    quality_path = sample_dir / "quality.json"
+    if not quality_path.is_file():
+        return None
+    if any(not (sample_dir / filename).is_file() for filename in STANDARD_SAMPLE_OUTPUTS):
+        return None
+    with quality_path.open("r", encoding="utf-8") as handle:
+        quality = json.load(handle)
+    if quality.get("sample_id") != sample_id:
+        return None
+    if quality.get("backend") != backend_name:
+        return None
+    # Old output roots did not distinguish raw prompt evidence from the
+    # high-recall-but-sanity-filtered evidence used by later hidden completion.
+    # Force an explicit rerun rather than silently reusing that weaker audit
+    # trail after this schema change.
+    if quality.get("obstacle_evidence_policy_version") != OBSTACLE_EVIDENCE_POLICY_VERSION:
+        return None
+    if quality.get("review_status") == "error" or quality.get("error"):
+        return None
+    return quality
+
+
+def safe_name(text: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", text.lower()).strip("_")
+
+
+def prompt_list(value: Any) -> list[str]:
+    """Normalize a prompt list while accepting the legacy JSON shape."""
+    if isinstance(value, str):
+        raw = [value]
+    elif isinstance(value, (list, tuple)):
+        raw = value
+    else:
+        raw = []
+    return list(dict.fromkeys(str(prompt).strip() for prompt in raw if str(prompt).strip()))
+
+
+def obstacle_prompt_resolution(
+    config: dict[str, Any], category: str, backend_name: str | None = None
+) -> dict[str, Any]:
+    """Resolve backend-aware obstacle prompts without breaking legacy configs.
+
+    When a backend-specific list is present it replaces the corresponding
+    legacy global/category list.  The other level still falls back separately,
+    so a config may specialize only global prompts or only one category.  With
+    ``backend_name=None`` the output is exactly the historical legacy union.
+    """
+    global_prompts = prompt_list(config.get("obstacle_prompts"))
+    category_map = config.get("category_obstacle_prompts")
+    category_prompts = prompt_list(
+        category_map.get(category) if isinstance(category_map, dict) else None
+    )
+    global_source = "legacy.obstacle_prompts"
+    category_source = "legacy.category_obstacle_prompts"
+    if backend_name:
+        by_backend = config.get("obstacle_prompts_by_backend")
+        if isinstance(by_backend, dict) and backend_name in by_backend:
+            global_prompts = prompt_list(by_backend.get(backend_name))
+            global_source = f"obstacle_prompts_by_backend.{backend_name}"
+        category_by_backend = config.get("category_obstacle_prompts_by_backend")
+        backend_categories = (
+            category_by_backend.get(backend_name)
+            if isinstance(category_by_backend, dict)
+            else None
+        )
+        if isinstance(backend_categories, dict) and category in backend_categories:
+            category_prompts = prompt_list(backend_categories.get(category))
+            category_source = (
+                f"category_obstacle_prompts_by_backend.{backend_name}.{category}"
+            )
+    prompts = list(dict.fromkeys([*global_prompts, *category_prompts]))
+    return {
+        "backend": backend_name,
+        "category": category,
+        "global_source": global_source,
+        "category_source": category_source,
+        "prompts": prompts,
+    }
+
+
+def obstacle_prompts_for_category(
+    config: dict[str, Any], category: str, backend_name: str | None = None
+) -> list[str]:
+    """Return backend-aware obstacle prompts, with legacy fallback support."""
+    return list(obstacle_prompt_resolution(config, category, backend_name)["prompts"])
+
+
+def as_mapping(value: Any) -> dict[str, Any]:
+    return dict(value) if isinstance(value, dict) else {}
+
+
+def merge_mappings(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Small recursive merge for backend-specific evidence policy overrides."""
+    result = dict(base)
+    for key, value in override.items():
+        if isinstance(value, dict) and isinstance(result.get(key), dict):
+            result[key] = merge_mappings(dict(result[key]), value)
+        else:
+            result[key] = value
+    return result
+
+
+def merge_prompt_config(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Merge a small, output-run-specific prompt overlay safely.
+
+    Nested objects are merged, while prompt lists are appended in stable
+    de-duplicated order.  This lets a finite remediation run add a narrowly
+    justified prompt without copying or silently editing the frozen base
+    configuration used by a control run.  Scalar policy values remain an
+    explicit override, so their provenance can be locked by the Slurm wrapper.
+    """
+    result = dict(base)
+    for key, value in override.items():
+        current = result.get(key)
+        if isinstance(current, dict) and isinstance(value, dict):
+            result[key] = merge_prompt_config(dict(current), value)
+        elif isinstance(current, list) and isinstance(value, list):
+            result[key] = list(dict.fromkeys([*current, *value]))
+        else:
+            result[key] = value
+    return result
+
+
+def float_or_default(value: Any, default: float) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return default
+
+
+def normalized_float_mapping(value: Any) -> dict[str, float]:
+    mapping = as_mapping(value)
+    return {
+        str(key).strip().lower(): float_or_default(item, 0.0)
+        for key, item in mapping.items()
+        if str(key).strip()
+    }
+
+
+def normalized_override_mapping(value: Any) -> dict[str, dict[str, Any]]:
+    mapping = as_mapping(value)
+    return {
+        str(key).strip().lower(): as_mapping(item)
+        for key, item in mapping.items()
+        if str(key).strip() and isinstance(item, dict)
+    }
+
+
+def resolve_obstacle_evidence_policy(
+    config: dict[str, Any], backend_name: str
+) -> dict[str, Any]:
+    """Compile a serializable trusted-obstacle-evidence policy.
+
+    New configs may use ``obstacle_evidence_policy`` and optional
+    ``obstacle_evidence_policy_by_backend.<backend>``.  The aliases
+    ``obstacle_all_detected_policy`` / ``..._by_backend`` are accepted for
+    early experiment configs.  In a legacy config, the existing
+    ``obstacle_maximum_area_ratio`` map becomes the per-prompt area cap,
+    confidence filtering remains disabled, and a conservative route-like
+    component guard protects downstream hidden completion from broad scene
+    surfaces.
+    """
+    base = as_mapping(
+        config.get("obstacle_evidence_policy", config.get("obstacle_all_detected_policy", {}))
+    )
+    by_backend = as_mapping(
+        config.get(
+            "obstacle_evidence_policy_by_backend",
+            config.get("obstacle_all_detected_policy_by_backend", {}),
+        )
+    )
+    backend_override = as_mapping(by_backend.get(backend_name))
+    raw = merge_mappings(base, backend_override)
+    legacy_maximums = normalized_float_mapping(config.get("obstacle_maximum_area_ratio"))
+    maximums = dict(legacy_maximums)
+    maximums.update(
+        normalized_float_mapping(
+            raw.get("maximum_area_ratio", raw.get("maximum_area_ratio_by_prompt", {}))
+        )
+    )
+    prompt_overrides = normalized_override_mapping(
+        raw.get("prompt_overrides", raw.get("prompts", {}))
+    )
+    confidence_by_prompt = normalized_float_mapping(
+        raw.get("minimum_confidence_by_prompt", raw.get("minimum_prompt_confidence_by_prompt", {}))
+    )
+    route_like_raw = as_mapping(
+        raw.get("route_like", raw.get("route_like_component_policy", {}))
+    )
+    # The default is intentionally conservative: broad horizontal/ground-like
+    # components are rejected from trusted evidence, but remain visible in
+    # obstacle_unfiltered_evidence.png for human recovery.
+    route_like = {
+        "enabled": bool(route_like_raw.get("enabled", True)),
+        "minimum_bbox_width_ratio": float_or_default(
+            route_like_raw.get("minimum_bbox_width_ratio"), 0.80
+        ),
+        "minimum_bbox_height_ratio": float_or_default(
+            route_like_raw.get("minimum_bbox_height_ratio"), 0.12
+        ),
+        "minimum_component_area_ratio": float_or_default(
+            route_like_raw.get("minimum_component_area_ratio"), 0.03
+        ),
+    }
+    default_maximum = float_or_default(
+        raw.get("default_maximum_area_ratio", maximums.get("default", 0.15)),
+        0.15,
+    )
+    return {
+        "version": OBSTACLE_EVIDENCE_POLICY_VERSION,
+        "backend": backend_name,
+        "source": {
+            "global": "obstacle_evidence_policy" if base else "legacy_defaults",
+            "backend_override_present": bool(backend_override),
+            "legacy_obstacle_maximum_area_ratio_used": bool(legacy_maximums),
+        },
+        "minimum_component_area_pixels": max(
+            1, int(float_or_default(raw.get("minimum_component_area_pixels"), 16.0))
+        ),
+        "minimum_component_area_ratio": max(
+            0.0, float_or_default(raw.get("minimum_component_area_ratio"), 0.00002)
+        ),
+        "minimum_prompt_confidence": min(
+            1.0,
+            max(
+                0.0,
+                float_or_default(
+                    raw.get(
+                        "minimum_prompt_confidence",
+                        raw.get("minimum_confidence", 0.0),
+                    ),
+                    0.0,
+                ),
+            ),
+        ),
+        "minimum_confidence_by_prompt": confidence_by_prompt,
+        "default_maximum_area_ratio": min(1.0, max(0.0, default_maximum)),
+        "maximum_area_ratio_by_prompt": maximums,
+        "full_frame_area_ratio": min(
+            1.0, max(0.0, float_or_default(raw.get("full_frame_area_ratio"), 0.90))
+        ),
+        "prompt_overrides": prompt_overrides,
+        "route_like": route_like,
+    }
+
+
+def evidence_minimum_component_area(policy: dict[str, Any], image_area: int) -> int:
+    return max(
+        int(policy["minimum_component_area_pixels"]),
+        int(round(image_area * float(policy["minimum_component_area_ratio"]))),
+    )
+
+
+def evidence_prompt_limits(prompt: str, policy: dict[str, Any]) -> tuple[float, float]:
+    key = prompt.strip().lower()
+    override = as_mapping(policy["prompt_overrides"].get(key))
+    confidence = float_or_default(
+        override.get(
+            "minimum_confidence",
+            policy["minimum_confidence_by_prompt"].get(key, policy["minimum_prompt_confidence"]),
+        ),
+        float(policy["minimum_prompt_confidence"]),
+    )
+    maximum_area = float_or_default(
+        override.get(
+            "maximum_area_ratio",
+            policy["maximum_area_ratio_by_prompt"].get(
+                key, policy["default_maximum_area_ratio"]
+            ),
+        ),
+        float(policy["default_maximum_area_ratio"]),
+    )
+    return min(1.0, max(0.0, confidence)), min(1.0, max(0.0, maximum_area))
+
+
+def save_mask(path: Path, mask: np.ndarray) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    Image.fromarray(mask.astype(np.uint8) * 255, mode="L").save(path)
+
+
+def save_red_mask(path: Path, mask: np.ndarray) -> None:
+    """Save an RGB review visualization while preserving obstacle.png as binary."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    color = np.zeros((*mask.shape, 3), dtype=np.uint8)
+    color[mask] = (230, 45, 45)
+    Image.fromarray(color, mode="RGB").save(path)
+
+
+def remove_small_components(mask: np.ndarray, minimum_area: int) -> np.ndarray:
+    count, labels, stats, _ = cv2.connectedComponentsWithStats(mask.astype(np.uint8), 8)
+    output = np.zeros_like(mask, dtype=bool)
+    for index in range(1, count):
+        if int(stats[index, cv2.CC_STAT_AREA]) >= minimum_area:
+            output |= labels == index
+    return output
+
+
+def retain_core_connected_union(union: np.ndarray, core: np.ndarray, minimum_area: int) -> np.ndarray:
+    union = remove_small_components(union, minimum_area)
+    count, labels, stats, _ = cv2.connectedComponentsWithStats(union.astype(np.uint8), 8)
+    output = np.zeros_like(union, dtype=bool)
+    for index in range(1, count):
+        component = labels == index
+        if int(stats[index, cv2.CC_STAT_AREA]) >= minimum_area and np.any(component & core):
+            output |= component
+    return output
+
+
+def retain_nearby_obstacles(
+    obstacle: np.ndarray,
+    target: np.ndarray,
+    minimum_area: int,
+    maximum_area_ratio: float = 0.15,
+) -> np.ndarray:
+    """Keep compact obstacle components spatially adjacent to the target surface."""
+    distance = max(9, int(round(min(target.shape) * 0.035)) | 1)
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (distance, distance))
+    nearby = cv2.dilate(target.astype(np.uint8), kernel).astype(bool)
+    count, labels, stats, _ = cv2.connectedComponentsWithStats(obstacle.astype(np.uint8), 8)
+    output = np.zeros_like(obstacle, dtype=bool)
+    image_area = obstacle.size
+    for index in range(1, count):
+        area = int(stats[index, cv2.CC_STAT_AREA])
+        component = labels == index
+        if (
+            area >= minimum_area
+            and area / image_area <= maximum_area_ratio
+            and np.any(component & nearby)
+        ):
+            output |= component
+    return output
+
+
+def retain_compact_obstacles(
+    obstacle: np.ndarray,
+    minimum_area: int,
+    maximum_area_ratio: float = 0.12,
+) -> np.ndarray:
+    """Keep compact scene obstacles without requiring target adjacency."""
+    count, labels, stats, _ = cv2.connectedComponentsWithStats(obstacle.astype(np.uint8), 8)
+    output = np.zeros_like(obstacle, dtype=bool)
+    image_area = obstacle.size
+    for index in range(1, count):
+        area = int(stats[index, cv2.CC_STAT_AREA])
+        if minimum_area <= area <= image_area * maximum_area_ratio:
+            output |= labels == index
+    return output
+
+
+def route_like_component_count(mask: np.ndarray, route_policy: dict[str, Any]) -> int:
+    """Count broad ground/route-like components that must not seed hidden masks."""
+    if not bool(route_policy.get("enabled", False)) or not np.any(mask):
+        return 0
+    count, _, stats, _ = cv2.connectedComponentsWithStats(mask.astype(np.uint8), 8)
+    height, width = mask.shape
+    route_like = 0
+    for index in range(1, count):
+        area = int(stats[index, cv2.CC_STAT_AREA])
+        width_ratio = float(stats[index, cv2.CC_STAT_WIDTH] / max(width, 1))
+        height_ratio = float(stats[index, cv2.CC_STAT_HEIGHT] / max(height, 1))
+        area_ratio = float(area / max(mask.size, 1))
+        if (
+            width_ratio >= float(route_policy["minimum_bbox_width_ratio"])
+            and height_ratio >= float(route_policy["minimum_bbox_height_ratio"])
+            and area_ratio >= float(route_policy["minimum_component_area_ratio"])
+        ):
+            route_like += 1
+    return route_like
+
+
+def trusted_obstacle_prompt_evidence(
+    *,
+    prompt: str,
+    group: str,
+    prediction: PromptPrediction,
+    minimum_component_area: int,
+    policy: dict[str, Any],
+) -> tuple[np.ndarray, np.ndarray, dict[str, Any]]:
+    """Return all cleaned evidence and the subset safe to seed hidden completion.
+
+    The first mask is intentionally high recall: it only removes microscopic
+    components.  The second is accepted only if its prompt confidence and
+    image-area sanity checks pass and it is not route-like.  Rejecting at the
+    prompt level makes the audit rationale easy to understand and guarantees
+    that a broad false positive cannot leak into ``obstacle_all_detected``.
+    """
+    cleaned = remove_small_components(prediction.mask, minimum_component_area)
+    minimum_confidence, maximum_area_ratio = evidence_prompt_limits(prompt, policy)
+    area_ratio = float(cleaned.mean())
+    reasons: list[str] = []
+    if not np.any(cleaned):
+        reasons.append("empty_after_small_component_removal")
+    if float(prediction.confidence) < minimum_confidence:
+        reasons.append("confidence_below_minimum")
+    if area_ratio > maximum_area_ratio:
+        reasons.append("area_ratio_exceeds_prompt_maximum")
+    if area_ratio > float(policy["full_frame_area_ratio"]):
+        reasons.append("area_ratio_exceeds_full_frame_guard")
+    route_like_count = route_like_component_count(cleaned, policy["route_like"])
+    if route_like_count:
+        reasons.append("route_like_component_detected")
+    accepted = not reasons
+    trusted = cleaned if accepted else np.zeros_like(cleaned)
+    decision = {
+        "prompt": prompt,
+        "group": group,
+        "confidence": round(float(prediction.confidence), 6),
+        "instance_count": int(prediction.instance_count),
+        "minimum_confidence": round(minimum_confidence, 6),
+        "maximum_area_ratio": round(maximum_area_ratio, 6),
+        "cleaned_pixels": int(cleaned.sum()),
+        "cleaned_area_ratio": round(area_ratio, 6),
+        "route_like_component_count": route_like_count,
+        "decision": "accepted" if accepted else "rejected",
+        "reasons": reasons,
+        "trusted_pixels": int(trusted.sum()),
+    }
+    return cleaned, trusted, decision
+
+
+def area_plausibility(area_ratio: float, minimum: float, maximum: float) -> float:
+    if area_ratio <= 0 or area_ratio < minimum / 2 or area_ratio > min(1.0, maximum * 1.2):
+        return 0.0
+    if minimum <= area_ratio <= maximum:
+        return 1.0
+    if area_ratio < minimum:
+        return max(0.0, area_ratio / minimum)
+    return max(0.0, 1.0 - (area_ratio - maximum) / max(1.0 - maximum, 1e-6))
+
+
+@dataclass
+class PromptPrediction:
+    mask: np.ndarray
+    confidence: float
+    instance_count: int
+    boxes: list[list[float]]
+
+
+class Sam3Backend:
+    name = "sam3"
+
+    def __init__(self, args: argparse.Namespace):
+        repo = Path(args.sam3_repo).resolve()
+        checkpoint = Path(args.sam3_checkpoint).resolve()
+        if not repo.is_dir():
+            raise FileNotFoundError(f"SAM 3 repository not found: {repo}")
+        if not checkpoint.is_file():
+            raise FileNotFoundError(
+                f"SAM 3 checkpoint not found: {checkpoint}. Accept the model terms and download sam3.pt first."
+            )
+        sys.path.insert(0, str(repo))
+        import torch
+        from sam3.model.sam3_image_processor import Sam3Processor
+        from sam3.model_builder import build_sam3_image_model
+
+        self.torch = torch
+        self.device = args.device
+        self.autocast_device = str(args.device).split(":", 1)[0]
+        self.autocast_dtype = torch.bfloat16
+        model = build_sam3_image_model(
+            device=args.device,
+            checkpoint_path=str(checkpoint),
+            load_from_HF=False,
+            compile=args.compile,
+        )
+        self.processor = Sam3Processor(
+            model,
+            device=args.device,
+            confidence_threshold=args.confidence_threshold,
+        )
+        self.state: dict[str, Any] | None = None
+
+    def begin_image(self, image: Image.Image) -> None:
+        with self.torch.autocast(
+            device_type=self.autocast_device,
+            dtype=self.autocast_dtype,
+            enabled=self.autocast_device == "cuda",
+        ):
+            self.state = self.processor.set_image(image)
+
+    def predict(self, prompt: str) -> PromptPrediction:
+        if self.state is None:
+            raise RuntimeError("begin_image must be called before predict")
+        with self.torch.autocast(
+            device_type=self.autocast_device,
+            dtype=self.autocast_dtype,
+            enabled=self.autocast_device == "cuda",
+        ):
+            output = self.processor.set_text_prompt(prompt, self.state)
+        masks_tensor = output["masks"]
+        scores_tensor = output["scores"]
+        boxes_tensor = output["boxes"]
+        if masks_tensor.numel() == 0:
+            shape = (int(output["original_height"]), int(output["original_width"]))
+            return PromptPrediction(np.zeros(shape, dtype=bool), 0.0, 0, [])
+        masks = masks_tensor.detach().cpu().numpy().astype(bool)
+        while masks.ndim > 3 and masks.shape[1] == 1:
+            masks = masks[:, 0]
+        union = np.any(masks, axis=0)
+        scores = scores_tensor.detach().float().cpu().numpy()
+        boxes = boxes_tensor.detach().float().cpu().numpy().tolist()
+        return PromptPrediction(union, float(scores.max()), int(len(scores)), boxes)
+
+
+class GroundedSamBackend:
+    name = "grounded_sam"
+
+    def __init__(self, args: argparse.Namespace):
+        repo = Path(args.grounded_sam_repo).resolve()
+        config = Path(args.grounding_dino_config).resolve()
+        dino_checkpoint = Path(args.grounding_dino_checkpoint).resolve()
+        sam_checkpoint = Path(args.sam_checkpoint).resolve()
+        for path in (repo, config, dino_checkpoint, sam_checkpoint):
+            if not path.exists():
+                raise FileNotFoundError(f"Required Grounded-SAM path not found: {path}")
+        sys.path[:0] = [str(repo), str(repo / "GroundingDINO"), str(repo / "segment_anything")]
+        import torch
+        import GroundingDINO.groundingdino.datasets.transforms as T
+        from GroundingDINO.groundingdino.models import build_model
+        from GroundingDINO.groundingdino.util.slconfig import SLConfig
+        from GroundingDINO.groundingdino.util.utils import clean_state_dict
+        from segment_anything import SamPredictor, sam_model_registry
+
+        model_args = SLConfig.fromfile(str(config))
+        model_args.device = args.device
+        if args.bert_path:
+            model_args.bert_base_uncased_path = str(Path(args.bert_path).resolve())
+        self.torch = torch
+        self.transforms = T.Compose(
+            [
+                T.RandomResize([800], max_size=1333),
+                T.ToTensor(),
+                T.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
+            ]
+        )
+        self.device = args.device
+        self.box_threshold = args.box_threshold
+        self.model = build_model(model_args)
+        checkpoint = torch.load(str(dino_checkpoint), map_location="cpu", weights_only=False)
+        self.model.load_state_dict(clean_state_dict(checkpoint["model"]), strict=False)
+        self.model.to(args.device).eval()
+        sam = sam_model_registry[args.sam_model_type](checkpoint=str(sam_checkpoint)).to(args.device)
+        self.predictor = SamPredictor(sam)
+        self.image_pil: Image.Image | None = None
+        self.image_tensor = None
+        self.image_rgb: np.ndarray | None = None
+
+    def begin_image(self, image: Image.Image) -> None:
+        self.image_pil = image
+        self.image_rgb = np.asarray(image)
+        self.image_tensor, _ = self.transforms(image, None)
+        self.predictor.set_image(self.image_rgb)
+
+    def predict(self, prompt: str) -> PromptPrediction:
+        if self.image_pil is None or self.image_tensor is None or self.image_rgb is None:
+            raise RuntimeError("begin_image must be called before predict")
+        caption = prompt.lower().strip()
+        if not caption.endswith("."):
+            caption += "."
+        with self.torch.inference_mode():
+            outputs = self.model(self.image_tensor[None].to(self.device), captions=[caption])
+        logits = outputs["pred_logits"].detach().cpu().sigmoid()[0]
+        boxes = outputs["pred_boxes"].detach().cpu()[0]
+        confidence = logits.max(dim=1).values
+        keep = confidence > self.box_threshold
+        boxes = boxes[keep]
+        confidence = confidence[keep]
+        height, width = self.image_rgb.shape[:2]
+        if boxes.shape[0] == 0:
+            return PromptPrediction(np.zeros((height, width), dtype=bool), 0.0, 0, [])
+        scale = self.torch.tensor([width, height, width, height], dtype=boxes.dtype)
+        boxes = boxes * scale
+        boxes[:, :2] -= boxes[:, 2:] / 2
+        boxes[:, 2:] += boxes[:, :2]
+        transformed = self.predictor.transform.apply_boxes_torch(boxes, (height, width)).to(self.device)
+        with self.torch.inference_mode():
+            masks, sam_scores, _ = self.predictor.predict_torch(
+                point_coords=None,
+                point_labels=None,
+                boxes=transformed,
+                multimask_output=False,
+            )
+        masks_np = masks[:, 0].detach().cpu().numpy().astype(bool)
+        combined_confidence = float(
+            math.sqrt(float(confidence.max()) * float(sam_scores.detach().cpu().max()))
+        )
+        return PromptPrediction(
+            np.any(masks_np, axis=0),
+            combined_confidence,
+            int(len(masks_np)),
+            boxes.tolist(),
+        )
+
+
+def build_backend(args: argparse.Namespace):
+    if args.backend == "sam3":
+        return Sam3Backend(args)
+    if args.backend == "grounded_sam":
+        return GroundedSamBackend(args)
+    raise ValueError(f"Unsupported backend: {args.backend}")
+
+
+def prompt_consensus(
+    predictions: list[PromptPrediction], minimum_area: int
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, dict[str, Any]]:
+    if not predictions:
+        raise ValueError("At least one prompt prediction is required")
+    masks = np.stack([prediction.mask for prediction in predictions])
+    votes = masks.sum(axis=0)
+    union = votes > 0
+    majority = max(2, math.ceil(len(predictions) / 2)) if len(predictions) > 1 else 1
+    core = votes >= majority
+    fallback = False
+    if not np.any(core) and np.any(union):
+        fallback = True
+        best_index = int(np.argmax([prediction.confidence for prediction in predictions]))
+        core = predictions[best_index].mask.copy()
+    candidate = retain_core_connected_union(union, core, minimum_area)
+    core = remove_small_components(core & candidate, minimum_area)
+    uncertain = candidate & ~core
+    union_area = int(candidate.sum())
+    agreement = float(core.sum() / union_area) if union_area else 0.0
+    confidences = [prediction.confidence for prediction in predictions]
+    metadata = {
+        "majority_vote": majority,
+        "fallback_to_best_prompt": fallback,
+        "agreement": round(agreement, 6),
+        "mean_prompt_confidence": round(float(np.mean(confidences)), 6),
+        "maximum_prompt_confidence": round(float(np.max(confidences)), 6),
+        "detected_prompt_count": sum(value > 0 for value in confidences),
+    }
+    return candidate, core, uncertain, metadata
+
+
+def overlay_masks(
+    image: np.ndarray, target: np.ndarray, obstacle: np.ndarray, uncertain: np.ndarray
+) -> np.ndarray:
+    overlay = image.astype(np.float32).copy()
+    colors = [
+        (target, np.asarray([30, 210, 70], dtype=np.float32), 0.38),
+        (uncertain, np.asarray([250, 210, 30], dtype=np.float32), 0.55),
+        # Draw obstacles last so target/uncertainty colors never hide red occluders.
+        (obstacle, np.asarray([230, 45, 45], dtype=np.float32), 0.58),
+    ]
+    for mask, color, alpha in colors:
+        overlay[mask] = overlay[mask] * (1.0 - alpha) + color * alpha
+    return np.clip(overlay, 0, 255).astype(np.uint8)
+
+
+def score_category(
+    mask: np.ndarray,
+    consensus: dict[str, Any],
+    thresholds: dict[str, float],
+    category: str,
+) -> tuple[float, dict[str, float]]:
+    area_ratio = float(mask.mean())
+    plausibility = area_plausibility(
+        area_ratio,
+        thresholds["minimum_target_area_ratio"],
+        thresholds["maximum_target_area_ratio"],
+    )
+    bottom_contact = float(mask[int(mask.shape[0] * 0.8) :, :].mean() > 0.005)
+    confidence = float(consensus["mean_prompt_confidence"])
+    agreement = float(consensus["agreement"])
+    evidence = 0.55 * confidence + 0.35 * agreement + 0.10 * bottom_contact
+    score = evidence * (0.20 + 0.80 * plausibility)
+    if category == "walkway":
+        score *= 0.94  # prevent the generic class from dominating specific structures
+    signals = {
+        "area_ratio": round(area_ratio, 6),
+        "area_plausibility": round(plausibility, 6),
+        "bottom_contact": bottom_contact,
+        "score": round(score, 6),
+    }
+    return score, signals
+
+
+def predict_prompt_set(
+    backend,
+    prompts: list[str],
+    output_dir: Path,
+    minimum_component_area: int,
+    save_prompt_masks: bool = True,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, dict[str, Any]]:
+    predictions = []
+    prompt_metadata = []
+    for prompt in prompts:
+        prediction = backend.predict(prompt)
+        predictions.append(prediction)
+        if save_prompt_masks:
+            save_mask(output_dir / f"{safe_name(prompt)}.png", prediction.mask)
+        prompt_metadata.append(
+            {
+                "prompt": prompt,
+                "confidence": round(prediction.confidence, 6),
+                "instance_count": prediction.instance_count,
+                "boxes_xyxy": prediction.boxes,
+            }
+        )
+    candidate, core, uncertain, consensus = prompt_consensus(
+        predictions, minimum_component_area
+    )
+    consensus["prompts"] = prompt_metadata
+    return candidate, core, uncertain, consensus
+
+
+def process_sample(
+    row: dict[str, Any],
+    backend,
+    config: dict[str, Any],
+    output_root: Path,
+    args: argparse.Namespace,
+) -> dict[str, Any]:
+    sample_id = row["sample_id"]
+    sample_dir = output_root / "samples" / sample_id
+    quality_path = sample_dir / "quality.json"
+    if args.resume:
+        quality = load_resume_quality(sample_dir, sample_id, backend.name)
+        if quality is not None:
+            return quality
+
+    # Phone photos commonly store the camera pixels in landscape orientation
+    # and rely on EXIF to display them upright.  Normalize that orientation
+    # before segmentation so every downstream mask uses the displayed frame.
+    image = ImageOps.exif_transpose(Image.open(row["image_path"])).convert("RGB")
+    rgb = np.asarray(image)
+    image_area = rgb.shape[0] * rgb.shape[1]
+    minimum_component_area = max(args.minimum_component_area, int(image_area * 0.0002))
+    backend.begin_image(image)
+
+    requested_categories = args.categories or list(config["categories"])
+    fixed_category = row.get("category")
+    if fixed_category:
+        requested_categories = [fixed_category]
+        if args.verify_manifest_category and not row.get("category_reviewed", False):
+            requested_categories.extend(
+                config.get("category_confusions", {}).get(fixed_category, [])
+            )
+            requested_categories = list(dict.fromkeys(requested_categories))
+
+    category_results: dict[str, dict[str, Any]] = {}
+    masks: dict[str, tuple[np.ndarray, np.ndarray, np.ndarray]] = {}
+    thresholds = config["quality_thresholds"]
+    save_full_artifacts = args.artifact_level == "full"
+    for category in requested_categories:
+        if category not in config["categories"]:
+            raise ValueError(f"Unknown category in pilot manifest: {category}")
+        prompt_dir = sample_dir / "prompts" / category
+        candidate, core, uncertain, consensus = predict_prompt_set(
+            backend,
+            config["categories"][category]["prompts"],
+            prompt_dir,
+            minimum_component_area,
+            save_prompt_masks=save_full_artifacts,
+        )
+        # --- per-category area cap (prevents whole-image over-segmentation) ---
+        cat_max_area = config["categories"][category].get(
+            "max_area_ratio",
+            config.get("tactile_paving_max_area_ratio", None),
+        )
+        candidate_area_ratio = float(candidate.mean()) if candidate.any() else 0.0
+        if cat_max_area is not None and candidate_area_ratio > float(cat_max_area):
+            consensus["area_cap_rejected"] = True
+            consensus["area_cap_ratio"] = round(candidate_area_ratio, 6)
+            consensus["area_cap_limit"] = float(cat_max_area)
+            candidate = np.zeros_like(candidate)
+            core = np.zeros_like(core)
+            uncertain = np.zeros_like(uncertain)
+        else:
+            consensus["area_cap_rejected"] = False
+        # --- end area cap ---
+        score, signals = score_category(candidate, consensus, thresholds, category)
+        if save_full_artifacts:
+            save_mask(sample_dir / "categories" / f"{category}_candidate.png", candidate)
+            save_mask(sample_dir / "categories" / f"{category}_core.png", core)
+            save_mask(sample_dir / "categories" / f"{category}_uncertain.png", uncertain)
+        masks[category] = (candidate, core, uncertain)
+        category_results[category] = {"consensus": consensus, **signals}
+
+    best_scored_category = max(
+        category_results, key=lambda key: category_results[key]["score"]
+    )
+    # A mask score is useful for flagging semantic disagreement, but it is not
+    # reliable enough to silently overwrite a manifest category. Human review
+    # overrides remain authoritative.
+    selected_category = fixed_category or best_scored_category
+    category_disagreement = bool(
+        fixed_category and best_scored_category != fixed_category
+    )
+    target, target_core, target_uncertain = masks[selected_category]
+
+    prompt_resolution = obstacle_prompt_resolution(
+        config, selected_category, backend.name
+    )
+    obstacle_predictions: list[tuple[str, PromptPrediction]] = []
+    obstacle_metadata = []
+    for prompt in prompt_resolution["prompts"]:
+        prediction = backend.predict(prompt)
+        obstacle_predictions.append((prompt, prediction))
+        if save_full_artifacts:
+            save_mask(
+                sample_dir / "prompts" / "obstacles" / f"{safe_name(prompt)}.png",
+                prediction.mask,
+            )
+        obstacle_metadata.append(
+            {
+                "prompt": prompt,
+                "group": "dynamic_or_compact",
+                "confidence": round(prediction.confidence, 6),
+                "instance_count": prediction.instance_count,
+                "boxes_xyxy": prediction.boxes,
+            }
+        )
+    maximum_ratios = config.get("obstacle_maximum_area_ratio", {})
+    filtered_dynamic_obstacles = []
+    for prompt, prediction in obstacle_predictions:
+        cleaned = remove_small_components(prediction.mask, minimum_component_area)
+        maximum_area_ratio = float(
+            maximum_ratios.get(prompt, maximum_ratios.get("default", 0.15))
+        )
+        filtered_dynamic_obstacles.append(
+            retain_nearby_obstacles(
+                cleaned,
+                target,
+                minimum_component_area,
+                maximum_area_ratio=maximum_area_ratio,
+            )
+        )
+    dynamic_obstacle = (
+        np.any(np.stack(filtered_dynamic_obstacles), axis=0)
+        if filtered_dynamic_obstacles
+        else np.zeros_like(target)
+    )
+
+    barrier_predictions: list[tuple[str, PromptPrediction]] = []
+    barrier_backends = config.get("barrier_obstacle_backends", ["sam3"])
+    barrier_prompts = (
+        config.get("barrier_obstacle_prompts", [])
+        if backend.name in barrier_backends
+        else []
+    )
+    for prompt in barrier_prompts:
+        prediction = backend.predict(prompt)
+        barrier_predictions.append((prompt, prediction))
+        if save_full_artifacts:
+            save_mask(
+                sample_dir / "prompts" / "obstacles" / f"{safe_name(prompt)}.png",
+                prediction.mask,
+            )
+        obstacle_metadata.append(
+            {
+                "prompt": prompt,
+                "group": "barrier_consensus",
+                "confidence": round(prediction.confidence, 6),
+                "instance_count": prediction.instance_count,
+                "boxes_xyxy": prediction.boxes,
+            }
+        )
+    if barrier_predictions:
+        barrier_votes = np.stack(
+            [prediction.mask for _, prediction in barrier_predictions]
+        ).sum(axis=0)
+        required_votes = max(2, math.ceil(len(barrier_predictions) / 2))
+        barrier_obstacle = barrier_votes >= required_votes
+        barrier_obstacle = retain_compact_obstacles(
+            barrier_obstacle, minimum_component_area
+        )
+    else:
+        barrier_obstacle = np.zeros_like(target)
+
+    # Keep two explicit evidence layers.  The unfiltered union is an audit
+    # artifact: every prompt after only microscopic-component removal.  The
+    # trusted union applies per-prompt confidence, prompt-area, full-frame,
+    # and broad-route sanity checks before it can seed a later hidden proposal.
+    # ``obstacle.png`` below intentionally keeps its original nearby policy.
+    evidence_policy = resolve_obstacle_evidence_policy(config, backend.name)
+    evidence_minimum_area = evidence_minimum_component_area(evidence_policy, image_area)
+    unfiltered_evidence_masks: list[np.ndarray] = []
+    trusted_evidence_masks: list[np.ndarray] = []
+    obstacle_evidence_decisions: list[dict[str, Any]] = []
+    for group, predictions in (
+        ("dynamic_or_compact", obstacle_predictions),
+        ("barrier_consensus", barrier_predictions),
+    ):
+        for prompt, prediction in predictions:
+            unfiltered, trusted, decision = trusted_obstacle_prompt_evidence(
+                prompt=prompt,
+                group=group,
+                prediction=prediction,
+                minimum_component_area=evidence_minimum_area,
+                policy=evidence_policy,
+            )
+            unfiltered_evidence_masks.append(unfiltered)
+            trusted_evidence_masks.append(trusted)
+            obstacle_evidence_decisions.append(decision)
+    obstacle_unfiltered_evidence = (
+        np.any(np.stack(unfiltered_evidence_masks), axis=0)
+        if unfiltered_evidence_masks
+        else np.zeros_like(target)
+    )
+    obstacle_all_detected = (
+        np.any(np.stack(trusted_evidence_masks), axis=0)
+        if trusted_evidence_masks
+        else np.zeros_like(target)
+    )
+    obstacle = dynamic_obstacle | barrier_obstacle
+    target = target & ~obstacle
+    target_core = target_core & target
+    target_uncertain = target_uncertain & target
+
+    kernel_size = max(5, int(round(min(rgb.shape[:2]) * 0.012)) | 1)
+    kernel = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (kernel_size, kernel_size))
+    target_dilated = cv2.dilate(target.astype(np.uint8), kernel).astype(bool)
+    obstacle_dilated = cv2.dilate(obstacle.astype(np.uint8), kernel).astype(bool)
+    adjacency = target_dilated & obstacle_dilated
+    adjacency_ratio = float(adjacency.sum() / max(target.sum(), 1))
+
+    save_mask(sample_dir / "target_visible_candidate.png", target)
+    save_mask(sample_dir / "target_visible_core.png", target_core)
+    save_mask(sample_dir / "target_uncertain.png", target_uncertain)
+    save_mask(sample_dir / "obstacle_unfiltered_evidence.png", obstacle_unfiltered_evidence)
+    save_mask(sample_dir / "obstacle_all_detected.png", obstacle_all_detected)
+    save_mask(sample_dir / "obstacle.png", obstacle)
+    save_red_mask(sample_dir / "obstacle_red.png", obstacle)
+    Image.fromarray(overlay_masks(rgb, target_core, obstacle, target_uncertain)).save(
+        sample_dir / "overlay.png", quality=92
+    )
+
+    selected = category_results[selected_category]
+    score = float(selected["score"])
+    target_area_ratio = float(target.mean())
+    uncertainty_ratio = float(target_uncertain.sum() / max(target.sum(), 1))
+    obstacle_area_ratio = float(obstacle.mean())
+    area_valid = (
+        thresholds["minimum_target_area_ratio"]
+        <= target_area_ratio
+        <= thresholds["maximum_target_area_ratio"]
+    )
+    if not area_valid:
+        review_status = "reject_or_reprompt"
+    elif (
+        score >= thresholds["auto_accept_score"]
+        and not selected["consensus"]["fallback_to_best_prompt"]
+        and uncertainty_ratio <= 0.35
+        and obstacle_area_ratio <= 0.20
+    ):
+        review_status = "candidate_accept_after_visual_review"
+    elif score >= thresholds["manual_review_score"]:
+        review_status = "manual_review"
+    else:
+        review_status = "reject_or_reprompt"
+    if (
+        category_disagreement
+        and not row.get("category_reviewed", False)
+        and review_status == "candidate_accept_after_visual_review"
+    ):
+        review_status = "manual_review"
+    quality = {
+        "sample_id": sample_id,
+        "image_path": row["image_path"],
+        "backend": backend.name,
+        "selected_category": selected_category,
+        "category_verification": {
+            "manifest_category": fixed_category,
+            "best_scored_category": best_scored_category,
+            "category_disagreement": category_disagreement,
+            "category_reviewed": bool(row.get("category_reviewed", False)),
+        },
+        "quality_score": round(score, 6),
+        "review_status": review_status,
+        "target_area_ratio": round(target_area_ratio, 6),
+        "target_core_ratio": round(float(target_core.mean()), 6),
+        "uncertainty_ratio_within_target": round(
+            uncertainty_ratio, 6
+        ),
+        "obstacle_area_ratio": round(obstacle_area_ratio, 6),
+        "obstacle_unfiltered_evidence_pixels": int(obstacle_unfiltered_evidence.sum()),
+        "obstacle_unfiltered_evidence_area_ratio": round(
+            float(obstacle_unfiltered_evidence.mean()), 6
+        ),
+        "obstacle_all_detected_pixels": int(obstacle_all_detected.sum()),
+        "obstacle_all_detected_area_ratio": round(float(obstacle_all_detected.mean()), 6),
+        "obstacle_all_detected_policy": "sanitized_high_recall_prompt_union_v2",
+        "obstacle_evidence_policy_version": OBSTACLE_EVIDENCE_POLICY_VERSION,
+        "obstacle_evidence_minimum_component_area_pixels": evidence_minimum_area,
+        "obstacle_evidence_artifact_semantics": {
+            "obstacle_unfiltered_evidence.png": (
+                "union of every obstacle/barrier prompt after only small-component removal; "
+                "audit evidence only, never direct hidden-completion support"
+            ),
+            "obstacle_all_detected.png": (
+                "high-recall prompt union after confidence, per-prompt area, full-frame, "
+                "and route-like sanity filters; candidate evidence for later hidden completion"
+            ),
+            "obstacle.png": (
+                "unchanged nearby/compact obstacle proposal used for visible-mask cleanup; "
+                "not the high-recall evidence layer"
+            ),
+        },
+        "obstacle_prompt_resolution": prompt_resolution,
+        "obstacle_evidence_policy": evidence_policy,
+        "obstacle_evidence_prompt_decisions": obstacle_evidence_decisions,
+        "obstacle_evidence_decision_counts": dict(
+            sorted(Counter(item["decision"] for item in obstacle_evidence_decisions).items())
+        ),
+        "barrier_obstacle_area_ratio": round(float(barrier_obstacle.mean()), 6),
+        "target_obstacle_adjacency_ratio": round(adjacency_ratio, 6),
+        "category_results": category_results,
+        "obstacle_prompts": obstacle_metadata,
+        "automatic_mask_is_ground_truth": False,
+        "artifact_level": args.artifact_level,
+    }
+    json_dump(quality_path, quality)
+    return quality
+
+
+def build_html_report(output_dir: Path, results: list[dict[str, Any]]) -> None:
+    rows = []
+    for result in sorted(results, key=lambda item: item.get("quality_score", -1), reverse=True):
+        sample_id = result["sample_id"]
+        overlay = f"samples/{sample_id}/overlay.png"
+        error = result.get("error")
+        details = html.escape(error) if error else (
+            f'{html.escape(result["selected_category"])} | '
+            f'score={result["quality_score"]:.3f} | '
+            f'{html.escape(result["review_status"])}'
+        )
+        rows.append(
+            f'<article><img src="{html.escape(overlay)}" loading="lazy">'
+            f'<div><strong>{html.escape(sample_id)}</strong><br>{details}</div></article>'
+        )
+    document = """<!doctype html><meta charset="utf-8"><title>Accessibility mask pilot</title>
+<style>body{font-family:sans-serif;margin:20px}main{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:16px}article{border:1px solid #bbb;padding:8px}img{width:100%;height:auto}div{margin-top:6px;font-size:14px}</style>
+<h1>Accessibility mask pilot</h1><p>Green: consensus core; yellow: uncertain target; red: obstacle. All masks require visual review.</p><main>"""
+    document += "\n".join(rows) + "</main>"
+    (output_dir / "report.html").write_text(document, encoding="utf-8")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--pilot-manifest", default="output/accessibility_clip_screen/pilot_manifest.jsonl")
+    parser.add_argument("--image", default=None, help="Single-image mode input image; bypasses --pilot-manifest.")
+    parser.add_argument("--single-sample-id", default=None, help="Stable output ID used with --image.")
+    parser.add_argument(
+        "--single-category",
+        choices=["curb_cut", "ramp", "stairs", "tactile_paving", "walkway"],
+        default=None,
+        help="Known category for --image. Omit to score all configured categories.",
+    )
+    parser.add_argument("--prompt-config", default="configs/accessibility_mask_prompts.json")
+    parser.add_argument(
+        "--prompt-config-override",
+        default=None,
+        help=(
+            "Optional JSON overlay merged into --prompt-config for this output-only run. "
+            "Nested prompt lists are appended and de-duplicated; the base config is never edited."
+        ),
+    )
+    parser.add_argument("--output-dir", default="output/accessibility_mask_proposals/sam3")
+    parser.add_argument("--backend", choices=["sam3", "grounded_sam"], default="sam3")
+    parser.add_argument("--device", default="cuda")
+    parser.add_argument("--categories", nargs="*", default=None)
+    parser.add_argument("--limit", type=int, default=0)
+    parser.add_argument("--minimum-component-area", type=int, default=128)
+    parser.add_argument("--confidence-threshold", type=float, default=0.38)
+    parser.add_argument("--compile", action="store_true")
+    parser.add_argument("--resume", action="store_true")
+    parser.add_argument(
+        "--artifact-level",
+        choices=["full", "standard"],
+        default="full",
+        help="standard omits regenerable per-prompt/category PNGs for large batch runs.",
+    )
+    parser.add_argument(
+        "--verify-manifest-category",
+        action="store_true",
+        help="Compare configured confusable categories unless category_reviewed=true.",
+    )
+    parser.add_argument(
+        "--allow-test-split",
+        action="store_true",
+        help=(
+            "Explicitly allow frozen test RGB rows for a pre-registered front-end "
+            "inference run. Default behavior remains validation-only."
+        ),
+    )
+    parser.add_argument("--sam3-repo", default="repos/sam3")
+    parser.add_argument("--sam3-checkpoint", default="weights/sam3/sam3.pt")
+    parser.add_argument(
+        "--grounded-sam-repo",
+        default="repos/grounded-sam-compat",
+    )
+    parser.add_argument(
+        "--grounding-dino-config",
+        default="repos/grounded-sam-compat/GroundingDINO/groundingdino/config/GroundingDINO_SwinT_OGC.py",
+    )
+    parser.add_argument(
+        "--grounding-dino-checkpoint",
+        default="weights/grounded-sam/groundingdino_swint_ogc.pth",
+    )
+    parser.add_argument(
+        "--sam-checkpoint",
+        default="weights/grounded-sam/sam_vit_h_4b8939.pth",
+    )
+    parser.add_argument("--sam-model-type", choices=["vit_h", "vit_l", "vit_b"], default="vit_h")
+    parser.add_argument("--bert-path", default=None)
+    parser.add_argument("--box-threshold", type=float, default=0.28)
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    config_path = Path(args.prompt_config).resolve()
+    config_override_path = (
+        Path(args.prompt_config_override).resolve()
+        if args.prompt_config_override
+        else None
+    )
+    output_dir = Path(args.output_dir).resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    with config_path.open("r", encoding="utf-8") as handle:
+        config = json.load(handle)
+    if not isinstance(config, dict):
+        raise ValueError(f"prompt config must be a JSON object: {config_path}")
+    if config_override_path is not None:
+        with config_override_path.open("r", encoding="utf-8") as handle:
+            override = json.load(handle)
+        if not isinstance(override, dict):
+            raise ValueError(f"prompt config override must be a JSON object: {config_override_path}")
+        config = merge_prompt_config(config, override)
+    if args.image:
+        image_path = Path(args.image).expanduser().resolve()
+        if not image_path.is_file():
+            raise FileNotFoundError(image_path)
+        sample_id = args.single_sample_id or safe_name(image_path.stem) or "single_image"
+        rows = [
+            {
+                "sample_id": sample_id,
+                "image_path": str(image_path),
+                "category": args.single_category,
+                "category_reviewed": bool(args.single_category),
+            }
+        ]
+    else:
+        pilot_path = Path(args.pilot_manifest).resolve()
+        rows = read_jsonl(pilot_path)
+    if args.limit > 0:
+        rows = rows[: args.limit]
+    allowed_splits = {None, "validation"}
+    if args.allow_test_split:
+        allowed_splits.add("test")
+    invalid_splits = sorted(
+        {str(row.get("benchmark_split")) for row in rows if row.get("benchmark_split") not in allowed_splits}
+    )
+    if invalid_splits:
+        raise ValueError(
+            "Proposal manifest contains unsupported benchmark split(s): "
+            f"{invalid_splits}. Pass --allow-test-split only for an explicitly "
+            "registered test front-end inference run."
+        )
+    test_accessed = any(row.get("benchmark_split") == "test" for row in rows)
+    backend = None
+    initialization_error = None
+    try:
+        backend = build_backend(args)
+        if backend.torch.cuda.is_available():
+            backend.torch.cuda.reset_peak_memory_stats()
+    except Exception as exc:
+        traceback.print_exc()
+        initialization_error = f"{type(exc).__name__}: {exc}"
+    results = []
+    if initialization_error is not None:
+        for row in rows:
+            results.append(
+                {
+                    "sample_id": row["sample_id"],
+                    "image_path": row["image_path"],
+                    "backend": args.backend,
+                    "quality_score": -1.0,
+                    "review_status": "error",
+                    "error": f"model_initialization_failed: {initialization_error}",
+                }
+            )
+        write_jsonl(output_dir / "results.jsonl", results)
+    else:
+        assert backend is not None
+        for index, row in enumerate(rows, start=1):
+            print(f"[{index}/{len(rows)}] {row['sample_id']}", flush=True)
+            try:
+                result = process_sample(row, backend, config, output_dir, args)
+            except Exception as exc:
+                traceback.print_exc()
+                result = {
+                    "sample_id": row["sample_id"],
+                    "image_path": row["image_path"],
+                    "backend": args.backend,
+                    "quality_score": -1.0,
+                    "review_status": "error",
+                    "error": f"{type(exc).__name__}: {exc}",
+                }
+            results.append(result)
+            write_jsonl(output_dir / "results.jsonl", results)
+    build_html_report(output_dir, results)
+    failed = sum(item.get("review_status") == "error" for item in results)
+    peak_bytes = (
+        int(backend.torch.cuda.max_memory_allocated())
+        if backend is not None and backend.torch.cuda.is_available()
+        else 0
+    )
+    summary = {
+        "backend": args.backend,
+        "sample_count": len(results),
+        "completed": len(results) - failed,
+        "failed": failed,
+        "failure_rate": failed / len(results) if results else 1.0,
+        "status_counts": dict(
+            sorted(
+                {
+                    status: sum(item.get("review_status") == status for item in results)
+                    for status in {item.get("review_status") for item in results}
+                }.items()
+            )
+        ),
+        "mean_quality_score": round(
+            float(np.mean([item["quality_score"] for item in results if item["quality_score"] >= 0])),
+            6,
+        )
+        if any(item["quality_score"] >= 0 for item in results)
+        else None,
+        "automatic_masks_are_ground_truth": False,
+        "prompt_config": str(config_path),
+        "prompt_config_override": str(config_override_path) if config_override_path else None,
+        "model_initialization_error": initialization_error,
+        "peak_gpu_memory_bytes": peak_bytes,
+        "peak_gpu_memory_gib": peak_bytes / (1024**3),
+        "environment": {
+            "python": sys.version,
+            "executable": sys.executable,
+            "torch": getattr(getattr(backend, "torch", None), "__version__", None),
+            "cuda_runtime": getattr(getattr(backend, "torch", None), "version", None).cuda
+            if backend is not None
+            else None,
+            "gpu_name": backend.torch.cuda.get_device_name(0)
+            if backend is not None and backend.torch.cuda.is_available()
+            else None,
+            "slurm_job_id": os.environ.get("SLURM_JOB_ID"),
+        },
+        "resolved_arguments": vars(args),
+        "test_accessed": test_accessed,
+        "test_access_explicitly_allowed": bool(args.allow_test_split),
+    }
+    json_dump(output_dir / "summary.json", summary)
+    print(json.dumps(summary, ensure_ascii=False, indent=2))
+    return 0 if all(item.get("review_status") != "error" for item in results) else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/audit_accessibility_3d_candidate.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""Write an auditable preflight and multiview verification report for one run."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+from PIL import Image
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(PROJECT_ROOT))
+
+from accessibilityamodal.verification import build_verification  # noqa: E402
+
+
+def read_json(path: Path) -> dict:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def read_mask(path: Path) -> np.ndarray:
+    mask = np.asarray(Image.open(path).convert("L")) > 127
+    return mask
+
+
+def find_sam_quality(run_dir: Path, sample_id: str) -> dict | None:
+    for root in (run_dir / "01_sam3", run_dir / "01_sam3_retry"):
+        path = root / "samples" / sample_id / "quality.json"
+        if path.is_file():
+            return read_json(path)
+    return None
+
+
+def find_reviewed_visible_metadata(run_dir: Path) -> dict | None:
+    path = run_dir / "01_reviewed_visible" / "metadata.json"
+    return read_json(path) if path.is_file() else None
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--run-dir", required=True)
+    parser.add_argument("--sample-id", required=True)
+    parser.add_argument("--category", required=True, choices=["curb_cut", "ramp", "stairs", "tactile_paving", "walkway"])
+    parser.add_argument("--output", default=None)
+    parser.add_argument("--preflight-only", action="store_true")
+    parser.add_argument("--print-decision", action="store_true")
+    args = parser.parse_args()
+
+    run_dir = Path(args.run_dir).expanduser().resolve()
+    masks_dir = run_dir / "02_masks"
+    visible = read_mask(masks_dir / "target_visible.png")
+    amodal = read_mask(masks_dir / "target_amodal.png")
+    hidden = read_mask(masks_dir / "hidden.png")
+    obstacle = read_mask(masks_dir / "obstacle.png")
+    geometry_path = run_dir / "04_3d_completion" / "geometry" / "geometry_manifest.json"
+    geometry = None if args.preflight_only or not geometry_path.is_file() else read_json(geometry_path)
+    learned_dir = None
+    if not args.preflight_only:
+        learned_candidates = (
+            run_dir / "accessibility3d",
+            run_dir / "04_3d_completion" / "visual_candidate",
+        )
+        learned_dir = next(
+            (candidate for candidate in learned_candidates if candidate.is_dir()),
+            learned_candidates[0],
+        )
+    report = build_verification(
+        sample_id=args.sample_id,
+        category=args.category,
+        visible_mask=visible,
+        amodal_mask=amodal,
+        hidden_mask=hidden,
+        obstacle_mask=obstacle,
+        sam3_quality=find_sam_quality(run_dir, args.sample_id),
+        reviewed_visible_metadata=find_reviewed_visible_metadata(run_dir),
+        geometry_manifest=geometry,
+        learned_dir=learned_dir,
+    )
+    output = (
+        Path(args.output).expanduser().resolve()
+        if args.output
+        else run_dir / "05_quality_checks" / "verification.json"
+    )
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, ensure_ascii=False, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    if args.print_decision:
+        print(report["decision"])
+    else:
+        print(json.dumps({"output": str(output), "decision": report["decision"], "gate": report["gate"]}, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/build_accessibility_review_bundle.py

@@ -0,0 +1,746 @@
+#!/usr/bin/env python3
+"""Build one orderly 2D/3D accessibility-completion quick-review directory."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import os
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Iterable, Mapping, Sequence
+
+from PIL import Image, ImageDraw, ImageOps
+
+
+PROFILES = ("walking", "blind_low_vision", "wheelchair_wheeled", "cyclist")
+PRIMARY_3D_ROLES = (
+    "category_geometry",
+    "open_world_accessibility_surface",
+    "learned_amodal3d_gaussian",
+)
+CORE_OUTPUT_NAMES = {
+    "original": "01_original.jpg",
+    "completion_2d": "02_2d_completion.png",
+    "geometry_turntable": "03_3d_turntable.gif",
+    "geometry_multiview": "04_3d_multiview.jpg",
+    "geometry_mesh": "05_mesh.ply",
+    "overview": "overview.jpg",
+    "accessibility_review": "accessibility_review.json",
+}
+VISUAL_OUTPUT_NAMES = {
+    "visual_turntable": "05_visual_3d_turntable.gif",
+    "visual_multiview": "06_visual_3d_multiview.jpg",
+}
+
+METRIC_ALIASES = {
+    "width": (
+        "clear_width_m",
+        "minimum_clear_width_m",
+        "min_clear_width_m",
+        "path_width_m",
+        "walkable_width_m",
+        "width_m",
+    ),
+    "slope": (
+        "slope_degrees",
+        "slope_percent",
+        "longitudinal_slope_percent",
+        "cross_slope_percent",
+        "slope_ratio",
+        "grade_percent",
+    ),
+    "clearance": (
+        "clearance_m",
+        "minimum_clearance_m",
+        "min_clearance_m",
+        "vertical_clearance_m",
+        "obstacle_clearance_m",
+    ),
+}
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--source", "--original", dest="source", required=True)
+    parser.add_argument(
+        "--completion-2d",
+        "--selected-2d",
+        "--2d-selected",
+        dest="completion_2d",
+        required=True,
+    )
+    parser.add_argument(
+        "--turntable-gif",
+        "--geometry-turntable",
+        dest="turntable_gif",
+        required=True,
+    )
+    parser.add_argument(
+        "--multiview",
+        "--geometry-multiview",
+        dest="multiview",
+        required=True,
+    )
+    parser.add_argument("--mesh", "--geometry-mesh", dest="mesh", required=True)
+    parser.add_argument(
+        "--primary-3d-role",
+        choices=PRIMARY_3D_ROLES,
+        default="category_geometry",
+        help=(
+            "Declares whether the core rotating review files are diagnostic "
+            "category geometry, an open-world accessibility surface, or the "
+            "Accessibility3D CUDA Gaussian/dense-mesh result."
+        ),
+    )
+    parser.add_argument("--completion-manifest", required=True)
+    parser.add_argument(
+        "--geometry-manifest",
+        default=None,
+        help="Optional geometry/depth manifest containing metric-evidence declarations.",
+    )
+    parser.add_argument(
+        "--verification-manifest",
+        default=None,
+        help=(
+            "Optional generated-3D verification report. Its exact bytes are bound "
+            "into the quick-review manifest so the selected primary role remains auditable."
+        ),
+    )
+    parser.add_argument(
+        "--visual-turntable",
+        default=None,
+        help="Optional learned visual 3D candidate; never used as passability evidence.",
+    )
+    parser.add_argument(
+        "--visual-multiview",
+        default=None,
+        help="Optional learned visual 3D candidate; never used as passability evidence.",
+    )
+    parser.add_argument("--category", required=True)
+    parser.add_argument("--sample-id", required=True)
+    parser.add_argument(
+        "--output-dir",
+        required=True,
+        help="Sample directory; files are written below its 00_quick_review child.",
+    )
+    return parser
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def relative_path(path: Path, anchor: Path) -> str:
+    return Path(os.path.relpath(path.resolve(), anchor.resolve())).as_posix()
+
+
+def file_record(path: Path, anchor: Path) -> dict[str, Any]:
+    return {
+        "path": relative_path(path, anchor),
+        "sha256": sha256_file(path),
+        "bytes": path.stat().st_size,
+    }
+
+
+def read_json_object(path: Path) -> dict[str, Any]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, dict):
+        raise ValueError(f"Expected a JSON object: {path}")
+    return value
+
+
+def write_json(path: Path, payload: Mapping[str, Any]) -> None:
+    path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def _walk_json(value: Any, prefix: tuple[str, ...] = ()) -> Iterable[tuple[tuple[str, ...], Any]]:
+    if isinstance(value, dict):
+        for key, child in value.items():
+            key_path = (*prefix, str(key))
+            yield key_path, child
+            yield from _walk_json(child, key_path)
+    elif isinstance(value, list):
+        for index, child in enumerate(value):
+            yield from _walk_json(child, (*prefix, str(index)))
+
+
+def _number(value: Any) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, (int, float)) and math.isfinite(float(value)):
+        return float(value)
+    if isinstance(value, dict):
+        return _number(value.get("value"))
+    return None
+
+
+def _measurement_unit(field: str) -> str:
+    if field.endswith("_m"):
+        return "m"
+    if field.endswith("_degrees"):
+        return "degrees"
+    if field.endswith("_percent") or field == "grade_percent":
+        return "percent"
+    if field.endswith("_ratio"):
+        return "ratio"
+    return "declared_metric"
+
+
+def _find_measurement(
+    manifests: Sequence[tuple[str, Mapping[str, Any]]],
+    aliases: Sequence[str],
+) -> dict[str, Any] | None:
+    alias_set = set(aliases)
+    for source_name, payload in manifests:
+        for key_path, value in _walk_json(payload):
+            field = key_path[-1]
+            if field not in alias_set:
+                continue
+            numeric_value = _number(value)
+            if numeric_value is None:
+                continue
+            unit = _measurement_unit(field)
+            if isinstance(value, dict) and isinstance(value.get("unit"), str):
+                unit = str(value["unit"])
+            return {
+                "value": numeric_value,
+                "unit": unit,
+                "source_manifest": source_name,
+                "source_field": ".".join(key_path),
+            }
+    return None
+
+
+def _metric_truth_declarations(
+    manifests: Sequence[tuple[str, Mapping[str, Any]]],
+) -> list[dict[str, Any]]:
+    truth_fields = {
+        "depth_is_metric_truth",
+        "depth_is_metric",
+        "geometry_is_metric",
+        "metric_geometry",
+        "metric_calibrated",
+    }
+    declarations: list[dict[str, Any]] = []
+    for source_name, payload in manifests:
+        for key_path, value in _walk_json(payload):
+            if key_path[-1] in truth_fields and isinstance(value, bool):
+                declarations.append(
+                    {
+                        "source_manifest": source_name,
+                        "source_field": ".".join(key_path),
+                        "value": value,
+                    }
+                )
+    return declarations
+
+
+def extract_metric_evidence(
+    completion_manifest: Mapping[str, Any],
+    geometry_manifest: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Extract only explicitly named physical measurements.
+
+    A width-like pixel count is deliberately not treated as metric evidence.
+    Measurements are trusted for passability review only when a supplied
+    manifest explicitly declares calibrated/metric geometry.
+    """
+    manifests: list[tuple[str, Mapping[str, Any]]] = [
+        ("completion_manifest", completion_manifest)
+    ]
+    if geometry_manifest is not None:
+        manifests.append(("geometry_manifest", geometry_manifest))
+    declarations = _metric_truth_declarations(manifests)
+    trusted_metric_geometry = any(item["value"] is True for item in declarations)
+    measurements = {
+        name: _find_measurement(manifests, aliases)
+        for name, aliases in METRIC_ALIASES.items()
+    }
+    missing = [name for name, measurement in measurements.items() if measurement is None]
+    complete = trusted_metric_geometry and not missing
+    return {
+        "trusted_metric_geometry": trusted_metric_geometry,
+        "metric_truth_declarations": declarations,
+        "measurements": measurements,
+        "missing_measurements": missing,
+        "complete_width_slope_clearance": complete,
+        "automatic_passability_allowed": False,
+        "reason": (
+            "Metric width, slope, and clearance are present, but thresholds and field "
+            "validation still require human review."
+            if complete
+            else "Trusted metric width, slope, and clearance are incomplete."
+        ),
+    }
+
+
+def is_stairs_category(category: str) -> bool:
+    normalized = category.strip().lower().replace("-", "_").replace(" ", "_")
+    return normalized in {"stairs", "stair", "staircase", "steps"} or normalized.startswith(
+        "stairs_"
+    )
+
+
+def build_population_assessments(
+    category: str,
+    metric_evidence: Mapping[str, Any],
+) -> dict[str, dict[str, Any]]:
+    """Return conservative per-population decisions without a safety claim."""
+    assessments: dict[str, dict[str, Any]] = {}
+    complete_metrics = bool(metric_evidence.get("complete_width_slope_clearance", False))
+    for profile in PROFILES:
+        if is_stairs_category(category) and profile == "wheelchair_wheeled":
+            assessments[profile] = {
+                "status": "blocked",
+                "decision": "block",
+                "can_pass": False,
+                "review_action": "stop_and_replan",
+                "reason": "Stair geometry blocks a wheeled route; use an alternate reviewed route.",
+                "basis": "category_rule_stairs_wheelchair",
+                "human_review_required": True,
+            }
+            continue
+        assessments[profile] = {
+            "status": "unknown",
+            "decision": "unknown",
+            "can_pass": None,
+            "review_action": "manual_review",
+            "reason": (
+                "Metric evidence exists, but no jurisdiction-specific thresholds or "
+                "field validation were supplied."
+                if complete_metrics
+                else "Trusted metric width, slope, and clearance are incomplete."
+            ),
+            "basis": (
+                "metric_evidence_requires_threshold_review"
+                if complete_metrics
+                else "insufficient_metric_width_slope_clearance"
+            ),
+            "human_review_required": True,
+        }
+    return assessments
+
+
+def _provenance_summary(payload: Mapping[str, Any]) -> dict[str, Any]:
+    """Keep truthful source identifiers without copying absolute paths."""
+    summary: dict[str, Any] = {}
+    scalar_fields = (
+        "pipeline",
+        "backend",
+        "output_kind",
+        "completion_method",
+        "warning",
+        "device",
+        "category",
+        "sample_id",
+    )
+    for field in scalar_fields:
+        value = payload.get(field)
+        if isinstance(value, (str, int, float, bool)) or value is None:
+            summary[field] = value
+    model = payload.get("model")
+    if isinstance(model, str) and model.strip():
+        # A backend/model identifier is useful provenance. If it is a local
+        # filesystem path, retain the final identifier rather than publishing an
+        # absolute host path.
+        summary["model_identifier"] = Path(model).name if ("/" in model or "\\" in model) else model
+    return summary
+
+
+def _save_image(source: Path, destination: Path, image_format: str) -> None:
+    image = ImageOps.exif_transpose(Image.open(source)).convert("RGB")
+    if image_format == "JPEG":
+        image.save(destination, format=image_format, quality=95, subsampling=0)
+    else:
+        image.save(destination, format=image_format)
+
+
+def copy_review_assets(
+    *,
+    source: Path,
+    completion_2d: Path,
+    turntable_gif: Path,
+    multiview: Path,
+    mesh: Path,
+    review_dir: Path,
+    visual_turntable: Path | None = None,
+    visual_multiview: Path | None = None,
+) -> dict[str, Path]:
+    review_dir.mkdir(parents=True, exist_ok=True)
+    outputs = {
+        role: review_dir / filename for role, filename in CORE_OUTPUT_NAMES.items()
+    }
+    _save_image(source, outputs["original"], "JPEG")
+    _save_image(completion_2d, outputs["completion_2d"], "PNG")
+    shutil.copy2(turntable_gif, outputs["geometry_turntable"])
+    _save_image(multiview, outputs["geometry_multiview"], "JPEG")
+    shutil.copy2(mesh, outputs["geometry_mesh"])
+
+    if visual_turntable is not None:
+        destination = review_dir / VISUAL_OUTPUT_NAMES["visual_turntable"]
+        shutil.copy2(visual_turntable, destination)
+        outputs["visual_turntable"] = destination
+    if visual_multiview is not None:
+        destination = review_dir / VISUAL_OUTPUT_NAMES["visual_multiview"]
+        _save_image(visual_multiview, destination, "JPEG")
+        outputs["visual_multiview"] = destination
+    return outputs
+
+
+def _panel(path: Path, label: str, size: tuple[int, int]) -> Image.Image:
+    image = ImageOps.exif_transpose(Image.open(path)).convert("RGB")
+    header_height = 42
+    body = ImageOps.contain(image, (size[0], size[1] - header_height))
+    panel = Image.new("RGB", size, "white")
+    draw = ImageDraw.Draw(panel)
+    draw.rectangle((0, 0, size[0], header_height), fill=(241, 241, 238))
+    draw.text((13, 14), label, fill=(18, 18, 18))
+    panel.paste(
+        body,
+        (
+            (size[0] - body.width) // 2,
+            header_height + (size[1] - header_height - body.height) // 2,
+        ),
+    )
+    return panel
+
+
+def build_overview(
+    *,
+    original: Path,
+    completion_2d: Path,
+    geometry_multiview: Path,
+    destination: Path,
+    category: str,
+    primary_3d_role: str = "category_geometry",
+) -> None:
+    if primary_3d_role == "learned_amodal3d_gaussian":
+        review_label = "03-05 Accessibility3D CUDA 3D review"
+    elif primary_3d_role == "open_world_accessibility_surface":
+        review_label = "03-05 Open-world accessibility surface review"
+    else:
+        review_label = "03-05 Diagnostic geometry review"
+    panel_size = (480, 500)
+    panels = [
+        _panel(original, "01 Original image", panel_size),
+        _panel(completion_2d, "02 2D completion candidate", panel_size),
+        _panel(
+            geometry_multiview,
+            review_label,
+            panel_size,
+        ),
+    ]
+    footer_height = 64
+    canvas = Image.new(
+        "RGB",
+        (panel_size[0] * len(panels), panel_size[1] + footer_height),
+        (231, 231, 228),
+    )
+    for index, panel in enumerate(panels):
+        canvas.paste(panel, (index * panel_size[0], 0))
+    draw = ImageDraw.Draw(canvas)
+    draw.text(
+        (14, panel_size[1] + 12),
+        (
+            f"Category: {category}. Review artifact only: do not infer safe passage "
+            "without metric width, slope, clearance, and human validation."
+        ),
+        fill=(90, 35, 28),
+    )
+    draw.text(
+        (14, panel_size[1] + 36),
+        (
+            "The 2D result is generative; the Accessibility3D rotation is a nonmetric "
+            "visual reconstruction, not a navigation certification."
+            if primary_3d_role == "learned_amodal3d_gaussian"
+            else "The 2D result is generative; the rotating geometry is not a navigation certification."
+        ),
+        fill=(70, 70, 70),
+    )
+    canvas.save(destination, quality=94, subsampling=0)
+
+
+def build_accessibility_review(
+    *,
+    sample_id: str,
+    category: str,
+    completion_manifest: Mapping[str, Any],
+    metric_evidence: Mapping[str, Any],
+    visual_candidate_present: bool,
+    primary_3d_role: str = "category_geometry",
+) -> dict[str, Any]:
+    assessments = build_population_assessments(category, metric_evidence)
+    if primary_3d_role == "learned_amodal3d_gaussian":
+        render_backend = "Accessibility3D CUDA Gaussian rasterization"
+        mesh_representation = "dense FlexiCubes triangle faces"
+    elif primary_3d_role == "open_world_accessibility_surface":
+        render_backend = "category-constrained open-world surface renderer"
+        mesh_representation = "open-world accessibility triangle surface patch"
+    else:
+        render_backend = "category-constrained geometry renderer"
+        mesh_representation = "category-constrained triangle mesh"
+    primary_review_name = (
+        "Accessibility3D learned nonmetric reconstruction"
+        if primary_3d_role == "learned_amodal3d_gaussian"
+        else "category-constrained diagnostic 3D geometry"
+    )
+    return {
+        "schema_version": "accessibilityamodal_review_v1",
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "sample_id": sample_id,
+        "category": category,
+        "overall_status": "manual_review_required",
+        "safe_passage_claim": False,
+        "population_assessments": assessments,
+        "metric_evidence": dict(metric_evidence),
+        "primary_3d_evidence": {
+            "turntable": CORE_OUTPUT_NAMES["geometry_turntable"],
+            "multiview": CORE_OUTPUT_NAMES["geometry_multiview"],
+            "mesh": CORE_OUTPUT_NAMES["geometry_mesh"],
+            "role": primary_3d_role,
+            "render_backend": render_backend,
+            "mesh_representation": mesh_representation,
+            "is_metric_geometry": False,
+            "is_navigation_certification": False,
+        },
+        "completion_2d": {
+            "path": CORE_OUTPUT_NAMES["completion_2d"],
+            "role": "generative_visual_hypothesis",
+            "is_ground_truth": False,
+        },
+        "visual_3d_candidate": {
+            "present": visual_candidate_present,
+            "role": "learned_visual_candidate_only",
+            "metric_evidence": False,
+            "passability_evidence": False,
+            "warning": (
+                "The learned visual candidate must not be used to infer dimensions or passage."
+                if visual_candidate_present
+                else None
+            ),
+        },
+        "completion_provenance": _provenance_summary(completion_manifest),
+        "required_human_checks": [
+            "Verify that the hidden ground/support surface is completed continuously, without fog, haze, or ghost obstacles.",
+            f"Verify that the 2D completion agrees with the selected {primary_review_name}.",
+            "Measure and validate route width, slope, and clearance before any passage decision.",
+        ],
+        "limitations": [
+            "No population is declared safely passable by this automatic bundle.",
+            "A blocked stairs/wheelchair rule is a route-level constraint, not a complete site assessment.",
+        ],
+    }
+
+
+def build_bundle(
+    *,
+    source: Path,
+    completion_2d: Path,
+    turntable_gif: Path,
+    multiview: Path,
+    mesh: Path,
+    completion_manifest_path: Path,
+    category: str,
+    sample_id: str,
+    output_dir: Path,
+    geometry_manifest_path: Path | None = None,
+    verification_manifest_path: Path | None = None,
+    visual_turntable: Path | None = None,
+    visual_multiview: Path | None = None,
+    primary_3d_role: str = "category_geometry",
+) -> Path:
+    if primary_3d_role not in PRIMARY_3D_ROLES:
+        raise ValueError(
+            f"Unsupported primary_3d_role={primary_3d_role!r}; "
+            f"expected one of {PRIMARY_3D_ROLES}"
+        )
+    input_paths = {
+        "source": source,
+        "completion_2d": completion_2d,
+        "geometry_turntable": turntable_gif,
+        "geometry_multiview": multiview,
+        "geometry_mesh": mesh,
+        "completion_manifest": completion_manifest_path,
+    }
+    if geometry_manifest_path is not None:
+        input_paths["geometry_manifest"] = geometry_manifest_path
+    if verification_manifest_path is not None:
+        input_paths["verification_manifest"] = verification_manifest_path
+    if visual_turntable is not None:
+        input_paths["visual_turntable"] = visual_turntable
+    if visual_multiview is not None:
+        input_paths["visual_multiview"] = visual_multiview
+    for role, path in input_paths.items():
+        if not path.is_file():
+            raise FileNotFoundError(f"Missing {role}: {path}")
+    if (visual_turntable is None) != (visual_multiview is None):
+        raise ValueError(
+            "--visual-turntable and --visual-multiview must be supplied together"
+        )
+
+    review_dir = (
+        output_dir if output_dir.name == "00_quick_review" else output_dir / "00_quick_review"
+    )
+    completion_manifest = read_json_object(completion_manifest_path)
+    geometry_manifest = (
+        read_json_object(geometry_manifest_path)
+        if geometry_manifest_path is not None
+        else None
+    )
+    verification_manifest = (
+        read_json_object(verification_manifest_path)
+        if verification_manifest_path is not None
+        else None
+    )
+    metric_evidence = extract_metric_evidence(completion_manifest, geometry_manifest)
+    outputs = copy_review_assets(
+        source=source,
+        completion_2d=completion_2d,
+        turntable_gif=turntable_gif,
+        multiview=multiview,
+        mesh=mesh,
+        review_dir=review_dir,
+        visual_turntable=visual_turntable,
+        visual_multiview=visual_multiview,
+    )
+    build_overview(
+        original=outputs["original"],
+        completion_2d=outputs["completion_2d"],
+        geometry_multiview=outputs["geometry_multiview"],
+        destination=outputs["overview"],
+        category=category,
+        primary_3d_role=primary_3d_role,
+    )
+    review = build_accessibility_review(
+        sample_id=sample_id,
+        category=category,
+        completion_manifest=completion_manifest,
+        metric_evidence=metric_evidence,
+        visual_candidate_present=(
+            visual_turntable is not None
+            or primary_3d_role == "learned_amodal3d_gaussian"
+        ),
+        primary_3d_role=primary_3d_role,
+    )
+    write_json(outputs["accessibility_review"], review)
+
+    output_records = {
+        role: file_record(path, review_dir)
+        for role, path in outputs.items()
+        if path.is_file()
+    }
+    input_records = {
+        role: file_record(path, review_dir) for role, path in input_paths.items()
+    }
+    manifest = {
+        "schema_version": "accessibilityamodal_quick_review_manifest_v1",
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "sample_id": sample_id,
+        "category": category,
+        "purpose": "fast_human_review_of_original_2d_and_3d_completion",
+        "primary_3d_role": primary_3d_role,
+        "inputs": input_records,
+        "files": output_records,
+        "review_summary": {
+            "overall_status": review["overall_status"],
+            "safe_passage_claim": False,
+            "wheelchair_wheeled": review["population_assessments"][
+                "wheelchair_wheeled"
+            ]["status"],
+        },
+        "visual_candidate_policy": {
+            "present": (
+                visual_turntable is not None
+                or primary_3d_role == "learned_amodal3d_gaussian"
+            ),
+            "role": "learned_visual_candidate",
+            "is_metric_evidence": False,
+            "is_passability_evidence": False,
+        },
+        "provenance": {
+            "completion_manifest": _provenance_summary(completion_manifest),
+            "geometry_manifest_supplied": geometry_manifest is not None,
+            "verification_manifest_supplied": verification_manifest is not None,
+            "verification_decision": (
+                verification_manifest.get("decision")
+                if verification_manifest is not None
+                else None
+            ),
+        },
+        "path_policy": "All filesystem paths in this manifest are relative to manifest.json.",
+        "integrity_note": "manifest.json omits its own hash to avoid recursive self-hashing.",
+    }
+    write_json(review_dir / "manifest.json", manifest)
+    return review_dir
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_argument_parser()
+    args = parser.parse_args(argv)
+    category = str(args.category).strip().lower()
+    sample_id = str(args.sample_id).strip()
+    if not category:
+        parser.error("--category must not be empty")
+    if not sample_id:
+        parser.error("--sample-id must not be empty")
+
+    review_dir = build_bundle(
+        source=Path(args.source).expanduser().resolve(),
+        completion_2d=Path(args.completion_2d).expanduser().resolve(),
+        turntable_gif=Path(args.turntable_gif).expanduser().resolve(),
+        multiview=Path(args.multiview).expanduser().resolve(),
+        mesh=Path(args.mesh).expanduser().resolve(),
+        completion_manifest_path=Path(args.completion_manifest).expanduser().resolve(),
+        geometry_manifest_path=(
+            Path(args.geometry_manifest).expanduser().resolve()
+            if args.geometry_manifest
+            else None
+        ),
+        verification_manifest_path=(
+            Path(args.verification_manifest).expanduser().resolve()
+            if args.verification_manifest
+            else None
+        ),
+        visual_turntable=(
+            Path(args.visual_turntable).expanduser().resolve()
+            if args.visual_turntable
+            else None
+        ),
+        visual_multiview=(
+            Path(args.visual_multiview).expanduser().resolve()
+            if args.visual_multiview
+            else None
+        ),
+        primary_3d_role=args.primary_3d_role,
+        category=category,
+        sample_id=sample_id,
+        output_dir=Path(args.output_dir).expanduser().resolve(),
+    )
+    print(
+        json.dumps(
+            {
+                "status": "built",
+                "sample_id": sample_id,
+                "review_dir": str(review_dir),
+                "safe_passage_claim": False,
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/render_accessibility_turntable.py

@@ -0,0 +1,1316 @@
+#!/usr/bin/env python3
+"""Render one accessibility geometry mesh into a compact turntable review set.
+
+Open3D is imported only after the render environment has been configured.  This
+keeps argument/manifest helpers usable on CPU-only review machines and makes a
+software fallback an explicit, auditable user choice.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Mapping, MutableMapping, Sequence
+
+import imageio.v2 as imageio
+import numpy as np
+from PIL import Image, ImageDraw, ImageOps
+
+
+REQUESTED_RENDERER = "Open3D/EGL"
+RENDERER_IMPLEMENTATION = "open3d.visualization.rendering.OffscreenRenderer"
+PRODUCTION_RENDER_DEVICE = "physical_nvidia_gpu"
+DOMINANT_COMPONENT_MIN_FACE_FRACTION = 0.90
+GL_VENDOR = 0x1F00
+GL_RENDERER = 0x1F01
+GL_VERSION = 0x1F02
+GL_STRING_NAMES = {
+    GL_VENDOR: "GL_VENDOR",
+    GL_RENDERER: "GL_RENDERER",
+    GL_VERSION: "GL_VERSION",
+}
+SOFTWARE_OPENGL_MARKERS = (
+    "llvmpipe",
+    "softpipe",
+    "swrast",
+    "software",
+    "swiftshader",
+    "lavapipe",
+)
+NVIDIA_EGL_VENDOR_JSON = Path(
+    "/usr/share/glvnd/egl_vendor.d/10_nvidia.json"
+)
+OUTPUT_NAMES = {
+    "video": "turntable.mp4",
+    "gif": "turntable.gif",
+    "poster": "turntable_poster.png",
+    "multiview": "multiview.jpg",
+}
+
+
+def parse_color(value: str) -> tuple[float, float, float, float]:
+    """Parse an RGB/RGBA command-line color in the inclusive [0, 1] range."""
+    values = [
+        float(item.strip())
+        for item in value.replace(":", ",").replace(";", ",").split(",")
+        if item.strip()
+    ]
+    if len(values) == 3:
+        values.append(1.0)
+    if len(values) != 4:
+        raise argparse.ArgumentTypeError("expected three or four comma-separated numbers")
+    if any(not math.isfinite(item) or item < 0.0 or item > 1.0 for item in values):
+        raise argparse.ArgumentTypeError("background components must be between 0 and 1")
+    return tuple(values)  # type: ignore[return-value]
+
+
+def parse_yaws(value: str) -> tuple[float, ...]:
+    """Parse the yaw angles used in the multiview contact sheet."""
+    try:
+        values = tuple(float(item.strip()) for item in value.split(",") if item.strip())
+    except ValueError as error:
+        raise argparse.ArgumentTypeError("multiview yaws must be comma-separated numbers") from error
+    if not values:
+        raise argparse.ArgumentTypeError("at least one multiview yaw is required")
+    if len(values) > 12:
+        raise argparse.ArgumentTypeError("at most 12 multiview yaws are supported")
+    if any(not math.isfinite(item) for item in values):
+        raise argparse.ArgumentTypeError("multiview yaws must be finite")
+    return values
+
+
+def build_argument_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "--mesh",
+        "--ply",
+        dest="mesh",
+        required=True,
+        help="Input triangle mesh. --ply is retained as a convenient alias.",
+    )
+    parser.add_argument("--output-dir", required=True)
+    parser.add_argument("--sample-id", default=None)
+    parser.add_argument("--category", default="unknown")
+    parser.add_argument("--width", type=int, default=960)
+    parser.add_argument("--height", type=int, default=720)
+    parser.add_argument("--frames", type=int, default=96)
+    parser.add_argument("--fps", type=int, default=24)
+    parser.add_argument("--fov", type=float, default=32.0)
+    parser.add_argument("--elevation", type=float, default=18.0)
+    parser.add_argument("--distance-scale", type=float, default=1.25)
+    parser.add_argument("--shader", default="defaultUnlit")
+    parser.add_argument(
+        "--vertex-colors-srgb",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "Treat byte RGB vertex colors sampled from photographs as sRGB. "
+            "Enabled by default to avoid linear-color whitening."
+        ),
+    )
+    parser.add_argument("--background", type=parse_color, default=parse_color("0.82,0.82,0.80,1"))
+    parser.add_argument("--smooth-iterations", type=int, default=0)
+    parser.add_argument(
+        "--orbit-mode",
+        choices=("full_360", "front_arc"),
+        default="front_arc",
+        help=(
+            "full_360 is a conventional object turntable. front_arc keeps an "
+            "open-world scene in camera-facing review views and avoids treating "
+            "its unobserved back side as reconstructed evidence."
+        ),
+    )
+    parser.add_argument(
+        "--orbit-span",
+        type=float,
+        default=140.0,
+        help="Total yaw span in degrees for --orbit-mode front_arc.",
+    )
+    parser.add_argument(
+        "--multiview-yaws",
+        type=parse_yaws,
+        default=parse_yaws("-60,-30,0,30,60"),
+        help=(
+            "Comma-separated camera-facing yaw angles. In front_arc mode every "
+            "angle must stay within half of --orbit-span."
+        ),
+    )
+    parser.add_argument(
+        "--require-vertex-colors",
+        action="store_true",
+        help=(
+            "Reject meshes without a complete finite RGB value for every rendered "
+            "vertex instead of silently producing an untextured white surface."
+        ),
+    )
+    parser.add_argument(
+        "--cpu-fallback",
+        action="store_true",
+        # Retained only for low-level renderer diagnostics and unit tests. It is
+        # intentionally absent from normal CLI help and every production
+        # orchestrator; production rendering is physical-NVIDIA-GPU only.
+        help=argparse.SUPPRESS,
+    )
+    return parser
+
+
+def validate_arguments(args: argparse.Namespace) -> None:
+    if args.width < 64 or args.height < 64:
+        raise ValueError("--width and --height must each be at least 64")
+    if args.frames < 2:
+        raise ValueError("--frames must be at least 2")
+    if args.fps < 1:
+        raise ValueError("--fps must be at least 1")
+    if not math.isfinite(args.fov) or not (5.0 <= args.fov < 170.0):
+        raise ValueError("--fov must satisfy 5 <= fov < 170")
+    if not math.isfinite(args.elevation):
+        raise ValueError("--elevation must be finite")
+    if not math.isfinite(args.distance_scale) or args.distance_scale <= 0:
+        raise ValueError("--distance-scale must be positive")
+    if args.smooth_iterations < 0:
+        raise ValueError("--smooth-iterations must be non-negative")
+    if not (20.0 <= args.orbit_span <= 240.0):
+        raise ValueError("--orbit-span must satisfy 20 <= span <= 240")
+    if args.orbit_mode == "front_arc":
+        half_span = 0.5 * args.orbit_span
+        if any(abs(yaw) > half_span + 1e-6 for yaw in args.multiview_yaws):
+            raise ValueError(
+                "front_arc multiview yaws must stay within half of --orbit-span"
+            )
+
+
+def _visibility_state(value: str | None) -> str:
+    if value is None:
+        return "unspecified"
+    if not value.strip() or value.strip().lower() in {"-1", "none", "void", "nodevfiles"}:
+        return "hidden_or_disabled"
+    return "configured_visible_set"
+
+
+def inspect_render_environment(
+    environment: Mapping[str, str] | None = None,
+    *,
+    cpu_fallback: bool = False,
+) -> dict[str, Any]:
+    """Return environment evidence without claiming that Open3D used a GPU.
+
+    CUDA visibility and EGL configuration are useful diagnostics, but neither
+    proves which physical renderer Filament selected.  The returned status is
+    intentionally conservative.
+    """
+    env = os.environ if environment is None else environment
+    cuda_visible = env.get("CUDA_VISIBLE_DEVICES")
+    egl_platform = env.get("EGL_PLATFORM")
+    software_value = env.get("LIBGL_ALWAYS_SOFTWARE")
+    software_requested = cpu_fallback or software_value == "1"
+    return {
+        "slurm": {
+            "job_id": env.get("SLURM_JOB_ID"),
+            "job_gpus": env.get("SLURM_JOB_GPUS"),
+            "gpu_allocation_present": bool(env.get("SLURM_JOB_ID")),
+        },
+        "egl": {
+            "platform": egl_platform,
+            "platform_configured": egl_platform is not None,
+            "visibility": "configured" if egl_platform is not None else "unspecified",
+            "device_id": env.get("EGL_DEVICE_ID"),
+            "gpu_use": "not_proven",
+        },
+        "cuda": {
+            "visible_devices": cuda_visible,
+            "visibility": _visibility_state(cuda_visible),
+            "used_by_renderer": "not_proven",
+        },
+        "software_rendering": {
+            "requested": software_requested,
+            "libgl_always_software": software_value,
+            "mesa_loader_driver_override": env.get("MESA_LOADER_DRIVER_OVERRIDE"),
+            "gallium_driver": env.get("GALLIUM_DRIVER"),
+        },
+        "hardware_acceleration": {
+            "status": (
+                "software_fallback_requested_backend_unverified"
+                if software_requested
+                else "hardware_backend_unverified"
+            ),
+            "reason": (
+                "Open3D OffscreenRenderer does not expose reliable physical-device "
+                "identity through this render path; environment visibility alone is "
+                "not hardware proof."
+            ),
+        },
+    }
+
+
+def require_slurm_gpu_environment(
+    environment: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Fail closed unless rendering runs inside a visible Slurm GPU allocation."""
+
+    env = os.environ if environment is None else environment
+    job_id = str(env.get("SLURM_JOB_ID") or "").strip()
+    cuda_visible = str(env.get("CUDA_VISIBLE_DEVICES") or "").strip()
+    if not job_id:
+        raise RuntimeError(
+            "GPU rendering is required by default and must run inside a Slurm "
+            "allocation. Use sbatch/srun, or explicitly pass --cpu-fallback "
+            "for a diagnostic software render."
+        )
+    if not cuda_visible or cuda_visible.lower() in {"-1", "none", "void", "nodevfiles"}:
+        raise RuntimeError(
+            "The Slurm render job has no visible CUDA device; refusing an "
+            "implicit CPU/software fallback."
+        )
+    return {
+        "policy": "slurm_gpu_required_unless_cpu_fallback_explicit",
+        "slurm_job_id": job_id,
+        "cuda_visible_devices": cuda_visible,
+        "gpu_allocation_contract_satisfied": True,
+    }
+
+
+def configure_render_environment(
+    cpu_fallback: bool,
+    environment: MutableMapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Configure EGL before importing Open3D and return auditable evidence."""
+    env = os.environ if environment is None else environment
+    original = {
+        key: env.get(key)
+        for key in (
+            "EGL_PLATFORM",
+            "CUDA_VISIBLE_DEVICES",
+            "__EGL_VENDOR_LIBRARY_FILENAMES",
+            "LIBGL_ALWAYS_SOFTWARE",
+            "MESA_LOADER_DRIVER_OVERRIDE",
+            "GALLIUM_DRIVER",
+        )
+    }
+    env.setdefault("EGL_PLATFORM", "surfaceless")
+    gpu_contract = None
+    if cpu_fallback:
+        env["LIBGL_ALWAYS_SOFTWARE"] = "1"
+        env.setdefault("MESA_LOADER_DRIVER_OVERRIDE", "llvmpipe")
+        env.setdefault("GALLIUM_DRIVER", "llvmpipe")
+    else:
+        gpu_contract = require_slurm_gpu_environment(env)
+        if NVIDIA_EGL_VENDOR_JSON.is_file():
+            env.setdefault(
+                "__EGL_VENDOR_LIBRARY_FILENAMES",
+                str(NVIDIA_EGL_VENDOR_JSON),
+            )
+    evidence = inspect_render_environment(env, cpu_fallback=cpu_fallback)
+    evidence["configuration"] = {
+        "original": original,
+        "egl_platform_defaulted_by_tool": original["EGL_PLATFORM"] is None,
+        "nvidia_egl_vendor_defaulted_by_tool": (
+            not cpu_fallback
+            and original["__EGL_VENDOR_LIBRARY_FILENAMES"] is None
+            and env.get("__EGL_VENDOR_LIBRARY_FILENAMES")
+            == str(NVIDIA_EGL_VENDOR_JSON)
+        ),
+        "cpu_fallback_explicit": cpu_fallback,
+        "gpu_contract": gpu_contract,
+    }
+    return evidence
+
+
+def _load_gl_get_string() -> tuple[Any, str]:
+    """Resolve ``glGetString`` without importing an OpenGL Python package.
+
+    Open3D wheels do not expose Filament's selected renderer through their
+    Python API.  Once ``OffscreenRenderer`` has created its EGL context, the GL
+    dispatch function is sufficient to query the active context directly.
+    """
+
+    import ctypes
+    import ctypes.util
+
+    attempts: list[str] = []
+    candidates: list[tuple[str, str | None]] = [("process", None)]
+    for library_name in ("GL", "OpenGL", "GLESv2"):
+        library_path = ctypes.util.find_library(library_name)
+        if library_path:
+            candidates.append((library_name, library_path))
+
+    for label, library_path in candidates:
+        try:
+            library = ctypes.CDLL(library_path)
+            gl_get_string = getattr(library, "glGetString")
+        except (AttributeError, OSError) as error:
+            attempts.append(f"{label}: {error}")
+            continue
+        gl_get_string.argtypes = [ctypes.c_uint]
+        gl_get_string.restype = ctypes.c_char_p
+        return gl_get_string, f"ctypes:{label}"
+
+    # Some EGL/GLES deployments expose GL entry points only through
+    # eglGetProcAddress.  Keep this as a final standards-based resolution path.
+    egl_path = ctypes.util.find_library("EGL")
+    if egl_path:
+        try:
+            egl = ctypes.CDLL(egl_path)
+            egl_get_proc_address = egl.eglGetProcAddress
+            egl_get_proc_address.argtypes = [ctypes.c_char_p]
+            egl_get_proc_address.restype = ctypes.c_void_p
+            address = egl_get_proc_address(b"glGetString")
+            if address:
+                prototype = ctypes.CFUNCTYPE(ctypes.c_char_p, ctypes.c_uint)
+                return prototype(address), "ctypes:EGL.eglGetProcAddress"
+            attempts.append("EGL.eglGetProcAddress: returned NULL")
+        except (AttributeError, OSError) as error:
+            attempts.append(f"EGL: {error}")
+
+    detail = "; ".join(attempts) or "no OpenGL libraries were discoverable"
+    raise RuntimeError(f"Could not resolve glGetString ({detail})")
+
+
+def _decode_gl_string(value: Any) -> str | None:
+    """Convert a ``glGetString`` result into a non-empty Python string."""
+
+    if value is None:
+        return None
+    if isinstance(value, bytes):
+        decoded = value.decode("utf-8", errors="replace")
+    elif isinstance(value, str):
+        decoded = value
+    else:
+        decoded = str(value)
+    decoded = decoded.strip()
+    return decoded or None
+
+
+def query_current_opengl_context(
+    gl_get_string: Any | None = None,
+    *,
+    query_source: str | None = None,
+) -> dict[str, Any]:
+    """Query the OpenGL strings for the context current on this thread.
+
+    The optional callable is an injection seam for CPU-only unit tests.  In
+    production this function is called immediately after constructing Open3D's
+    ``OffscreenRenderer``.
+    """
+
+    evidence: dict[str, Any] = {
+        "query_api": "glGetString",
+        "query_source": query_source,
+        "query_succeeded": False,
+        "GL_VENDOR": None,
+        "GL_RENDERER": None,
+        "GL_VERSION": None,
+        "software_renderer_detected": False,
+        "software_markers": [],
+        "verification_status": "active_context_unverified",
+        "error": None,
+    }
+    try:
+        if gl_get_string is None:
+            gl_get_string, resolved_source = _load_gl_get_string()
+            evidence["query_source"] = resolved_source
+        elif evidence["query_source"] is None:
+            evidence["query_source"] = "injected_gl_get_string"
+
+        errors: list[str] = []
+        for enum_value, field_name in GL_STRING_NAMES.items():
+            try:
+                evidence[field_name] = _decode_gl_string(gl_get_string(enum_value))
+            except Exception as error:  # ctypes failures must become fail-closed evidence.
+                errors.append(f"{field_name}: {type(error).__name__}: {error}")
+        missing = [name for name in GL_STRING_NAMES.values() if not evidence[name]]
+        if missing:
+            errors.append("NULL or empty values: " + ", ".join(missing))
+        evidence["query_succeeded"] = not errors
+        if errors:
+            evidence["error"] = "; ".join(errors)
+    except Exception as error:
+        evidence["error"] = f"{type(error).__name__}: {error}"
+
+    combined = " ".join(
+        str(evidence[name] or "").lower() for name in GL_STRING_NAMES.values()
+    )
+    markers = [marker for marker in SOFTWARE_OPENGL_MARKERS if marker in combined]
+    evidence["software_markers"] = markers
+    evidence["software_renderer_detected"] = bool(markers)
+    if evidence["query_succeeded"]:
+        evidence["verification_status"] = (
+            "active_software_context_verified"
+            if markers
+            else "active_non_software_context_verified"
+        )
+    return evidence
+
+
+def inspect_process_graphics_backend(
+    *,
+    maps_text: str | None = None,
+    fd_targets: Sequence[str] | None = None,
+    environment: Mapping[str, str] | None = None,
+) -> dict[str, Any]:
+    """Inspect process-wide EGL libraries and open GPU device handles.
+
+    Filament owns its OpenGL context on an internal render thread, so
+    ``glGetString`` from the Python thread may legitimately return NULL.  In
+    that case a process-wide NVIDIA EGL binding plus an open physical
+    ``/dev/nvidiaN`` handle is stronger evidence than CUDA visibility alone.
+    Injection seams keep this policy fully unit-testable without a GPU.
+    """
+
+    env = os.environ if environment is None else environment
+    errors: list[str] = []
+    if maps_text is None:
+        try:
+            maps_text = Path("/proc/self/maps").read_text(
+                encoding="utf-8",
+                errors="replace",
+            )
+        except OSError as error:
+            maps_text = ""
+            errors.append(f"maps: {type(error).__name__}: {error}")
+    if fd_targets is None:
+        discovered_targets: list[str] = []
+        try:
+            for entry in Path("/proc/self/fd").iterdir():
+                try:
+                    discovered_targets.append(os.readlink(entry))
+                except OSError:
+                    continue
+        except OSError as error:
+            errors.append(f"fd: {type(error).__name__}: {error}")
+        fd_targets = discovered_targets
+
+    mapped_paths = sorted(
+        {
+            line.rsplit(None, 1)[-1]
+            for line in maps_text.splitlines()
+            if line.strip() and "/" in line.rsplit(None, 1)[-1]
+        }
+    )
+    nvidia_egl_libraries = [
+        path
+        for path in mapped_paths
+        if (
+            "libegl_nvidia" in path.lower()
+            or "libnvidia-eglcore" in path.lower()
+        )
+    ]
+    software_library_markers = sorted(
+        {
+            marker
+            for path in mapped_paths
+            for marker in (
+                "libegl_mesa",
+                "llvmpipe",
+                "softpipe",
+                "swrast",
+                "lavapipe",
+                "swiftshader",
+            )
+            if marker in path.lower()
+        }
+    )
+    gpu_device_fds = sorted(
+        {target for target in fd_targets if target.startswith("/dev/nvidia")}
+    )
+    physical_gpu_fds = [
+        target
+        for target in gpu_device_fds
+        if re.fullmatch(r"/dev/nvidia\d+", target)
+    ]
+    nvidia_backend_verified = bool(
+        nvidia_egl_libraries
+        and physical_gpu_fds
+        and not software_library_markers
+    )
+    return {
+        "inspection_api": "/proc/self/maps + /proc/self/fd",
+        "nvidia_egl_libraries": nvidia_egl_libraries,
+        "software_library_markers": software_library_markers,
+        "gpu_device_fds": gpu_device_fds,
+        "physical_gpu_fds": physical_gpu_fds,
+        "forced_egl_vendor_json": env.get(
+            "__EGL_VENDOR_LIBRARY_FILENAMES"
+        ),
+        "nvidia_process_backend_verified": nvidia_backend_verified,
+        "verification_status": (
+            "nvidia_egl_and_physical_device_fd_verified"
+            if nvidia_backend_verified
+            else "process_graphics_backend_unverified"
+        ),
+        "errors": errors,
+    }
+
+
+def enforce_opengl_context_policy(
+    opengl_context: Mapping[str, Any],
+    *,
+    cpu_fallback: bool,
+    process_backend: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Apply the fail-closed GPU policy to actual active-context evidence."""
+
+    query_succeeded = bool(opengl_context.get("query_succeeded"))
+    software_detected = bool(opengl_context.get("software_renderer_detected"))
+    renderer_name = opengl_context.get("GL_RENDERER")
+    nvidia_process_verified = bool(
+        process_backend
+        and process_backend.get("nvidia_process_backend_verified")
+    )
+
+    if cpu_fallback:
+        if not query_succeeded:
+            status = "cpu_fallback_requested_context_unverified"
+            reason = (
+                "Explicit --cpu-fallback permits diagnostic rendering even though "
+                "the active OpenGL strings could not be verified."
+            )
+        elif software_detected:
+            status = "software_fallback_active_context_verified"
+            reason = (
+                "Explicit --cpu-fallback was requested and the active OpenGL "
+                "context identifies a software renderer."
+            )
+        else:
+            status = "cpu_fallback_requested_non_software_context_verified"
+            reason = (
+                "Explicit --cpu-fallback was requested, but the active OpenGL "
+                "strings do not identify a known software renderer."
+            )
+        return {
+            "status": status,
+            "reason": reason,
+            "active_context_verified": query_succeeded,
+            "software_renderer_detected": software_detected,
+            "physical_gpu_identity_proven": False,
+        }
+
+    if software_detected:
+        markers = ", ".join(
+            str(value) for value in opengl_context.get("software_markers", [])
+        )
+        raise RuntimeError(
+            "The active OpenGL context is a software OpenGL renderer "
+            f"(GL_RENDERER={renderer_name!r}; markers={markers}); refusing the "
+            "default GPU render. Use --cpu-fallback to opt in explicitly."
+        )
+    if nvidia_process_verified:
+        physical_gpu_fds = list(
+            process_backend.get("physical_gpu_fds", [])
+            if process_backend is not None
+            else []
+        )
+        return {
+            "status": "active_nvidia_egl_process_backend_verified",
+            "reason": (
+                (
+                    "The active OpenGL context contains no software-renderer "
+                    "marker, and the renderer process loaded NVIDIA EGL without "
+                    "a known software library and opened a physical NVIDIA GPU "
+                    "device."
+                )
+                if query_succeeded
+                else (
+                    "Filament's render-thread GL strings were not visible to "
+                    "Python, but the renderer process loaded NVIDIA EGL without "
+                    "a known software library and opened a physical NVIDIA GPU "
+                    "device."
+                )
+            ),
+            "active_context_verified": query_succeeded,
+            "process_backend_verified": True,
+            "software_renderer_detected": False,
+            "physical_gpu_identity_proven": True,
+            "physical_gpu_fds": physical_gpu_fds,
+        }
+    if not query_succeeded:
+        detail = str(opengl_context.get("error") or "no GL strings were returned")
+        raise RuntimeError(
+            "Could not verify the active OpenGL context after creating "
+            f"OffscreenRenderer; refusing the default GPU render ({detail}). "
+            "Use --cpu-fallback only for an explicit diagnostic software render."
+        )
+    raise RuntimeError(
+        "The active OpenGL strings contain no known software marker, but the "
+        "renderer process did not prove an NVIDIA EGL backend plus a physical "
+        "/dev/nvidiaN device; refusing the default GPU render. Use "
+        "--cpu-fallback only for an explicit diagnostic software render."
+    )
+
+
+def _merge_runtime_graphics_evidence(
+    environment_evidence: Mapping[str, Any],
+    render_result: Mapping[str, Any],
+) -> dict[str, Any]:
+    """Combine pre-import environment facts with post-context GL evidence."""
+
+    merged = dict(environment_evidence)
+    opengl_context = render_result.get("opengl_context")
+    process_backend = render_result.get("process_graphics_backend")
+    hardware_acceleration = render_result.get("hardware_acceleration")
+    if isinstance(opengl_context, Mapping):
+        merged["opengl_context"] = dict(opengl_context)
+    if isinstance(process_backend, Mapping):
+        merged["process_graphics_backend"] = dict(process_backend)
+    if isinstance(hardware_acceleration, Mapping):
+        merged["hardware_acceleration"] = dict(hardware_acceleration)
+    return merged
+
+
+def relative_path(path: Path, anchor: Path) -> str:
+    """Return a portable relative path, even for an input outside ``anchor``."""
+    return Path(os.path.relpath(path.resolve(), anchor.resolve())).as_posix()
+
+
+def file_record(path: Path, anchor: Path) -> dict[str, Any]:
+    import hashlib
+
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return {
+        "path": relative_path(path, anchor),
+        "sha256": digest.hexdigest(),
+        "bytes": path.stat().st_size,
+    }
+
+
+def build_render_manifest(
+    *,
+    mesh_path: Path,
+    output_dir: Path,
+    sample_id: str,
+    category: str,
+    render_settings: Mapping[str, Any],
+    render_result: Mapping[str, Any],
+    environment_evidence: Mapping[str, Any],
+    cpu_fallback: bool,
+) -> dict[str, Any]:
+    """Build a manifest whose filesystem paths are all relative."""
+    runtime_evidence = _merge_runtime_graphics_evidence(
+        environment_evidence,
+        render_result,
+    )
+    opengl_context = dict(runtime_evidence.get("opengl_context", {}))
+    process_backend = dict(
+        runtime_evidence.get("process_graphics_backend", {})
+    )
+    outputs = {
+        role: file_record(output_dir / filename, output_dir)
+        for role, filename in OUTPUT_NAMES.items()
+    }
+    return {
+        "schema_version": "accessibilityamodal_turntable_v2",
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+        "sample_id": sample_id,
+        "category": category,
+        "requested_renderer": REQUESTED_RENDERER,
+        "renderer": {
+            "requested": REQUESTED_RENDERER,
+            "implementation": RENDERER_IMPLEMENTATION,
+            "production_render_device": PRODUCTION_RENDER_DEVICE,
+            "production_gpu_fail_closed": True,
+            "requested_execution": (
+                "cpu_fallback_explicit"
+                if cpu_fallback
+                else "slurm_gpu_required_egl"
+            ),
+            "cpu_fallback_explicit": cpu_fallback,
+            "gpu_required_by_default": True,
+            "render_call_succeeded": True,
+            "hardware_acceleration_status": runtime_evidence[
+                "hardware_acceleration"
+            ]["status"],
+            "opengl_context": opengl_context,
+            "process_graphics_backend": process_backend,
+        },
+        "environment_evidence": runtime_evidence,
+        "input": {
+            "mesh": file_record(mesh_path, output_dir),
+        },
+        "outputs": outputs,
+        "render_settings": dict(render_settings),
+        "mesh_summary": {
+            "vertices": int(render_result["vertices"]),
+            "renderable_vertices": int(
+                render_result.get("renderable_vertices", render_result["vertices"])
+            ),
+            "unreferenced_vertices_excluded_from_camera_fit": int(
+                render_result.get(
+                    "unreferenced_vertices_excluded_from_camera_fit",
+                    0,
+                )
+            ),
+            "faces": int(render_result["faces"]),
+            "camera_framing": dict(render_result.get("camera_framing", {})),
+            "camera_motion": dict(render_result.get("camera", {})),
+            "vertex_colors": dict(render_result.get("vertex_colors", {})),
+        },
+        "scene_review": dict(render_result.get("orbit", {})),
+        "limitations": [
+            "GPU mode rejects known software GL strings; when Filament keeps its context on a render thread, NVIDIA EGL mappings plus a physical /dev/nvidiaN handle provide process-backend proof.",
+            "When one connected surface contains at least 90% of faces, camera framing prioritizes it; detached islands remain in the mesh but may fall outside a close-up view.",
+            "front_arc shows the observed scene-facing hemisphere and intentionally does not claim an inferred back side.",
+            "This rotating geometry is review evidence, not metric accessibility or navigation certification.",
+        ],
+        "path_policy": "All filesystem paths in this manifest are relative to manifest.json.",
+    }
+
+
+def _camera_pose(
+    center: np.ndarray,
+    camera_distance: float,
+    yaw_degrees: float,
+    elevation_degrees: float,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    yaw = math.radians(yaw_degrees)
+    elevation = math.radians(elevation_degrees)
+    # ``camera_distance`` already includes the requested framing margin.  Keep
+    # that margin in one place so --distance-scale is not applied twice.
+    distance = max(camera_distance, 1e-3)
+    eye = center + np.array(
+        [
+            distance * math.sin(yaw) * math.cos(elevation),
+            -distance * math.cos(yaw) * math.cos(elevation),
+            distance * math.sin(elevation),
+        ],
+        dtype=np.float64,
+    )
+    return eye, center, np.array([0.0, 0.0, 1.0], dtype=np.float64)
+
+
+def _orbit_yaws(
+    frames: int,
+    *,
+    mode: str,
+    span_degrees: float,
+) -> list[float]:
+    """Return deterministic yaw positions for object or open-scene review."""
+
+    if frames < 2:
+        raise ValueError("orbit requires at least two frames")
+    if mode == "full_360":
+        return [360.0 * index / frames for index in range(frames)]
+    if mode != "front_arc":
+        raise ValueError(f"Unsupported orbit mode: {mode}")
+    half_span = 0.5 * float(span_degrees)
+    # Begin at the input-facing view, sweep right, return through the front,
+    # sweep left, and finish near the front. This loops without a 360-degree
+    # discontinuity and never claims an unobserved back-side reconstruction.
+    return [
+        half_span * math.sin(2.0 * math.pi * index / frames)
+        for index in range(frames)
+    ]
+
+
+def _fitted_camera_distance(
+    bbox_extent: np.ndarray,
+    vertical_fov_degrees: float,
+    aspect_ratio: float,
+) -> float:
+    radius = max(float(np.linalg.norm(bbox_extent)) * 0.5, 1e-3)
+    vertical_fov = math.radians(vertical_fov_degrees)
+    horizontal_fov = 2.0 * math.atan(math.tan(vertical_fov * 0.5) * aspect_ratio)
+    limiting_fov = min(vertical_fov, horizontal_fov)
+    return radius / max(math.sin(limiting_fov * 0.5), 1e-3)
+
+
+def _fitted_camera_distance_for_view(
+    vertices: np.ndarray,
+    center: np.ndarray,
+    *,
+    yaw_degrees: float,
+    elevation_degrees: float,
+    vertical_fov_degrees: float,
+    aspect_ratio: float,
+    distance_scale: float,
+) -> float:
+    """Fit an elongated surface for one view without a global-sphere zoom-out."""
+
+    yaw = math.radians(yaw_degrees)
+    elevation = math.radians(elevation_degrees)
+    eye_direction = np.array(
+        [
+            math.sin(yaw) * math.cos(elevation),
+            -math.cos(yaw) * math.cos(elevation),
+            math.sin(elevation),
+        ],
+        dtype=np.float64,
+    )
+    forward = -eye_direction
+    world_up = np.array([0.0, 0.0, 1.0], dtype=np.float64)
+    right = np.cross(forward, world_up)
+    right_norm = float(np.linalg.norm(right))
+    if right_norm < 1e-8:
+        right = np.array([1.0, 0.0, 0.0], dtype=np.float64)
+    else:
+        right /= right_norm
+    view_up = np.cross(right, forward)
+    view_up /= max(float(np.linalg.norm(view_up)), 1e-8)
+
+    relative = np.asarray(vertices, dtype=np.float64) - center
+    projected_x = np.abs(relative @ right)
+    projected_y = np.abs(relative @ view_up)
+    toward_camera = relative @ eye_direction
+    vertical_half_fov = math.radians(vertical_fov_degrees) * 0.5
+    horizontal_half_fov = math.atan(
+        math.tan(vertical_half_fov) * aspect_ratio
+    )
+    required_x = toward_camera + projected_x / max(
+        math.tan(horizontal_half_fov),
+        1e-6,
+    )
+    required_y = toward_camera + projected_y / max(
+        math.tan(vertical_half_fov),
+        1e-6,
+    )
+    fitted = max(float(np.max(required_x)), float(np.max(required_y)), 1e-3)
+    return fitted * distance_scale
+
+
+def _fixed_camera_distance_for_views(
+    vertices: np.ndarray,
+    center: np.ndarray,
+    *,
+    yaw_degrees: Sequence[float],
+    elevation_degrees: float,
+    vertical_fov_degrees: float,
+    aspect_ratio: float,
+    distance_scale: float,
+) -> tuple[float, dict[str, Any]]:
+    """Fit every requested view once and use the largest distance for all frames."""
+
+    unique_yaws = tuple(dict.fromkeys(float(yaw) for yaw in yaw_degrees))
+    if not unique_yaws:
+        raise ValueError("fixed camera fitting requires at least one yaw")
+    if any(not math.isfinite(yaw) for yaw in unique_yaws):
+        raise ValueError("fixed camera fitting requires finite yaws")
+    required_distances = [
+        _fitted_camera_distance_for_view(
+            vertices,
+            center,
+            yaw_degrees=yaw,
+            elevation_degrees=elevation_degrees,
+            vertical_fov_degrees=vertical_fov_degrees,
+            aspect_ratio=aspect_ratio,
+            distance_scale=distance_scale,
+        )
+        for yaw in unique_yaws
+    ]
+    fixed_distance = max(required_distances)
+    return fixed_distance, {
+        "distance_policy": "fixed_max_over_orbit_and_multiview",
+        "fixed_distance": float(fixed_distance),
+        "fit_yaw_count": len(unique_yaws),
+        "fit_yaw_min": float(min(unique_yaws)),
+        "fit_yaw_max": float(max(unique_yaws)),
+        "per_view_required_distance_min": float(min(required_distances)),
+        "per_view_required_distance_max": float(max(required_distances)),
+    }
+
+
+def _summarize_vertex_colors(
+    vertex_colors: np.ndarray,
+    vertex_count: int,
+    *,
+    required: bool,
+) -> dict[str, Any]:
+    """Return auditable texture evidence without inferring visual quality."""
+
+    colors = np.asarray(vertex_colors, dtype=np.float64)
+    complete = (
+        vertex_count > 0
+        and colors.ndim == 2
+        and colors.shape == (vertex_count, 3)
+    )
+    finite = bool(complete and np.isfinite(colors).all())
+    summary: dict[str, Any] = {
+        "required": bool(required),
+        "present": bool(complete),
+        "finite": finite,
+        "colored_vertices": int(colors.shape[0]) if colors.ndim == 2 else 0,
+        "coverage_fraction": 1.0 if complete else 0.0,
+    }
+    if finite:
+        summary.update(
+            {
+                "channel_mean": [float(value) for value in np.mean(colors, axis=0)],
+                "channel_std": [float(value) for value in np.std(colors, axis=0)],
+                "channel_min": [float(value) for value in np.min(colors, axis=0)],
+                "channel_max": [float(value) for value in np.max(colors, axis=0)],
+            }
+        )
+    return summary
+
+
+def _referenced_vertex_indices(
+    triangles: np.ndarray,
+    vertex_count: int,
+) -> np.ndarray:
+    """Return the vertices that can contribute pixels to a triangle render.
+
+    Some reconstruction meshes retain point-cloud vertices that are not
+    referenced by any triangle.  Those vertices are invisible, and a single
+    far-away orphan must not expand the camera bounds and shrink the actual
+    surface to a few pixels.
+    """
+
+    faces = np.asarray(triangles, dtype=np.int64)
+    if faces.ndim != 2 or faces.shape[1] != 3 or faces.size == 0:
+        raise ValueError("camera framing requires at least one triangular face")
+    referenced = np.unique(faces.reshape(-1))
+    if int(referenced[0]) < 0 or int(referenced[-1]) >= vertex_count:
+        raise ValueError("triangle index is outside the mesh vertex array")
+    return referenced
+
+
+def _camera_framing_vertex_indices(
+    triangles: np.ndarray,
+    triangle_component_labels: np.ndarray,
+    *,
+    dominant_component_min_face_fraction: float = DOMINANT_COMPONENT_MIN_FACE_FRACTION,
+) -> tuple[np.ndarray, dict[str, Any]]:
+    """Choose a review framing surface without letting tiny islands zoom out.
+
+    A strongly dominant connected triangle surface represents the primary
+    accessibility target in these reconstructions.  Small detached islands can
+    still be rendered, but they should not make the target unreadably small.
+    When no component owns at least 90% of faces, all triangle vertices remain
+    in the camera fit so legitimate multi-part geometry is not guessed away.
+    """
+
+    faces = np.asarray(triangles, dtype=np.int64)
+    labels = np.asarray(triangle_component_labels, dtype=np.int64).reshape(-1)
+    referenced = _referenced_vertex_indices(faces, int(faces.max()) + 1)
+    if labels.shape[0] != faces.shape[0] or np.any(labels < 0):
+        raise ValueError("triangle component labels must match triangular faces")
+    if not (0.0 < dominant_component_min_face_fraction <= 1.0):
+        raise ValueError("dominant component face fraction must be in (0, 1]")
+
+    counts = np.bincount(labels)
+    dominant_label = int(np.argmax(counts))
+    dominant_faces = int(counts[dominant_label])
+    face_count = int(faces.shape[0])
+    dominant_fraction = dominant_faces / face_count
+    use_dominant = dominant_fraction >= dominant_component_min_face_fraction
+    if use_dominant:
+        framing = np.unique(faces[labels == dominant_label].reshape(-1))
+        scope = "dominant_connected_surface"
+    else:
+        framing = referenced
+        scope = "all_connected_surfaces"
+    return framing, {
+        "scope": scope,
+        "framing_faces": dominant_faces if use_dominant else face_count,
+        "framing_vertices": int(len(framing)),
+        "dominant_component_faces": dominant_faces,
+        "dominant_component_face_fraction": float(dominant_fraction),
+        "component_count": int(len(counts)),
+        "minimum_dominant_face_fraction": float(
+            dominant_component_min_face_fraction
+        ),
+    }
+
+
+def _contact_sheet(images: Sequence[np.ndarray], labels: Sequence[str], path: Path) -> None:
+    columns = 2 if len(images) > 1 else 1
+    rows = math.ceil(len(images) / columns)
+    panel_width = 480
+    panel_height = 390
+    label_height = 34
+    canvas = Image.new(
+        "RGB",
+        (panel_width * columns, panel_height * rows),
+        (235, 235, 232),
+    )
+    for index, (array, label) in enumerate(zip(images, labels)):
+        image = Image.fromarray(array).convert("RGB")
+        body = ImageOps.contain(image, (panel_width, panel_height - label_height))
+        panel = Image.new("RGB", (panel_width, panel_height), "white")
+        draw = ImageDraw.Draw(panel)
+        draw.rectangle((0, 0, panel_width, label_height), fill=(242, 242, 239))
+        draw.text((12, 11), label, fill=(20, 20, 20))
+        panel.paste(
+            body,
+            (
+                (panel_width - body.width) // 2,
+                label_height + (panel_height - label_height - body.height) // 2,
+            ),
+        )
+        canvas.paste(panel, ((index % columns) * panel_width, (index // columns) * panel_height))
+    canvas.save(path, quality=94, subsampling=0)
+
+
+def render_outputs(
+    mesh_path: Path,
+    output_dir: Path,
+    *,
+    width: int,
+    height: int,
+    frames: int,
+    fps: int,
+    fov: float,
+    elevation: float,
+    distance_scale: float,
+    shader: str,
+    background: Sequence[float],
+    smooth_iterations: int,
+    multiview_yaws: Sequence[float],
+    orbit_mode: str = "front_arc",
+    orbit_span: float = 140.0,
+    require_vertex_colors: bool = False,
+    vertex_colors_srgb: bool = True,
+    cpu_fallback: bool = False,
+) -> dict[str, Any]:
+    """Render all outputs through Open3D's OffscreenRenderer path."""
+    import open3d as o3d
+    from open3d.visualization import rendering
+
+    mesh = o3d.io.read_triangle_mesh(str(mesh_path))
+    if len(mesh.vertices) == 0 or len(mesh.triangles) == 0:
+        raise ValueError(f"Input is not a non-empty triangle mesh: {mesh_path}")
+
+    source_vertex_count = len(mesh.vertices)
+    referenced_indices = _referenced_vertex_indices(
+        np.asarray(mesh.triangles, dtype=np.int64),
+        source_vertex_count,
+    )
+    unreferenced_vertex_count = source_vertex_count - len(referenced_indices)
+    # Open3D's scene bounds can include vertices that have no incident face,
+    # even though rasterization cannot display them.  Remove only these
+    # topologically inert points before both rendering and camera fitting.
+    if unreferenced_vertex_count:
+        mesh.remove_unreferenced_vertices()
+
+    # Geometry produced from image-camera coordinates is easier to inspect after
+    # mapping x/right, z/up, and -y/depth into a conventional scene frame.
+    vertices = np.asarray(mesh.vertices, dtype=np.float64)
+    mesh.vertices = o3d.utility.Vector3dVector(
+        np.stack([vertices[:, 0], vertices[:, 2], -vertices[:, 1]], axis=1)
+    )
+    if smooth_iterations:
+        mesh = mesh.filter_smooth_laplacian(number_of_iterations=smooth_iterations)
+    mesh.compute_vertex_normals()
+    vertex_color_summary = _summarize_vertex_colors(
+        np.asarray(mesh.vertex_colors, dtype=np.float64),
+        len(mesh.vertices),
+        required=require_vertex_colors,
+    )
+    if require_vertex_colors and not (
+        vertex_color_summary["present"] and vertex_color_summary["finite"]
+    ):
+        raise ValueError(
+            "Input mesh does not provide complete finite vertex colors required "
+            f"for texture-preserving rendering: {mesh_path}"
+        )
+
+    transformed_vertices = np.asarray(mesh.vertices, dtype=np.float64)
+    triangle_component_labels, _, _ = mesh.cluster_connected_triangles()
+    framing_indices, framing_summary = _camera_framing_vertex_indices(
+        np.asarray(mesh.triangles, dtype=np.int64),
+        np.asarray(triangle_component_labels, dtype=np.int64),
+    )
+    framing_vertices = transformed_vertices[framing_indices]
+    framing_min = np.min(framing_vertices, axis=0)
+    framing_max = np.max(framing_vertices, axis=0)
+    center = (framing_min + framing_max) * 0.5
+    orbit_yaws = _orbit_yaws(
+        frames,
+        mode=orbit_mode,
+        span_degrees=orbit_span,
+    )
+    fixed_camera_distance, camera_summary = _fixed_camera_distance_for_views(
+        framing_vertices,
+        center,
+        yaw_degrees=tuple(orbit_yaws) + tuple(multiview_yaws),
+        elevation_degrees=elevation,
+        vertical_fov_degrees=fov,
+        aspect_ratio=width / height,
+        distance_scale=distance_scale,
+    )
+
+    output_dir.mkdir(parents=True, exist_ok=True)
+    renderer = rendering.OffscreenRenderer(width, height)
+    try:
+        opengl_context = query_current_opengl_context()
+        process_graphics_backend = inspect_process_graphics_backend()
+        hardware_acceleration = enforce_opengl_context_policy(
+            opengl_context,
+            cpu_fallback=cpu_fallback,
+            process_backend=process_graphics_backend,
+        )
+        renderer.scene.set_background(list(background))
+        renderer.scene.scene.set_sun_light(
+            [0.35, -0.5, -0.75],
+            [1.0, 0.97, 0.92],
+            65000,
+        )
+        renderer.scene.scene.enable_sun_light(True)
+        renderer.scene.show_axes(False)
+        material = rendering.MaterialRecord()
+        material.shader = shader
+        material.sRGB_color = bool(vertex_colors_srgb)
+        material.base_color = [1.0, 1.0, 1.0, 1.0]
+        material.base_roughness = 0.68
+        material.base_reflectance = 0.18
+        renderer.scene.add_geometry("accessibility_geometry", mesh, material)
+
+        def render_yaw(yaw: float) -> np.ndarray:
+            eye, look_at, up = _camera_pose(
+                center,
+                fixed_camera_distance,
+                yaw,
+                elevation,
+            )
+            renderer.setup_camera(fov, look_at, eye, up)
+            array = np.asarray(renderer.render_to_image())
+            if array.ndim != 3 or array.shape[2] not in (3, 4):
+                raise RuntimeError(f"Unexpected Open3D render shape: {array.shape}")
+            return array[..., :3].astype(np.uint8, copy=False)
+
+        video_frames = [render_yaw(yaw) for yaw in orbit_yaws]
+        imageio.mimsave(
+            output_dir / OUTPUT_NAMES["video"],
+            video_frames,
+            fps=fps,
+            quality=8,
+            macro_block_size=1,
+        )
+        imageio.mimsave(
+            output_dir / OUTPUT_NAMES["gif"],
+            video_frames,
+            duration=1000.0 / fps,
+            loop=0,
+        )
+        Image.fromarray(video_frames[0]).save(output_dir / OUTPUT_NAMES["poster"])
+
+        views = [render_yaw(yaw) for yaw in multiview_yaws]
+        labels = [f"Geometry view {yaw:g} deg" for yaw in multiview_yaws]
+        _contact_sheet(views, labels, output_dir / OUTPUT_NAMES["multiview"])
+    finally:
+        release = getattr(renderer, "release_resources", None)
+        if callable(release):
+            release()
+
+    return {
+        "vertices": source_vertex_count,
+        "renderable_vertices": len(mesh.vertices),
+        "unreferenced_vertices_excluded_from_camera_fit": unreferenced_vertex_count,
+        "faces": len(mesh.triangles),
+        "camera_framing": framing_summary,
+        "camera": camera_summary,
+        "vertex_colors": vertex_color_summary,
+        "opengl_context": opengl_context,
+        "process_graphics_backend": process_graphics_backend,
+        "hardware_acceleration": hardware_acceleration,
+        "orbit": {
+            "mode": orbit_mode,
+            "span_degrees": float(orbit_span),
+            "yaw_min": float(min(orbit_yaws)),
+            "yaw_max": float(max(orbit_yaws)),
+            "multiview_yaws": [float(yaw) for yaw in multiview_yaws],
+            "open_world_scene_review": orbit_mode == "front_arc",
+        },
+    }
+
+
+def write_json(path: Path, payload: Mapping[str, Any]) -> None:
+    path.write_text(
+        json.dumps(payload, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_argument_parser()
+    args = parser.parse_args(argv)
+    validate_arguments(args)
+
+    mesh_path = Path(args.mesh).expanduser().resolve()
+    if not mesh_path.is_file():
+        raise FileNotFoundError(mesh_path)
+    output_dir = Path(args.output_dir).expanduser().resolve()
+    output_dir.mkdir(parents=True, exist_ok=True)
+    sample_id = str(args.sample_id or mesh_path.stem)
+    category = str(args.category).strip().lower() or "unknown"
+
+    environment_evidence = configure_render_environment(args.cpu_fallback)
+    render_settings = {
+        "resolution": [args.width, args.height],
+        "frames": args.frames,
+        "fps": args.fps,
+        "fov_degrees": args.fov,
+        "elevation_degrees": args.elevation,
+        "distance_scale": args.distance_scale,
+        "camera_fit": "fixed_max_projected_primary_surface_v4",
+        "camera_distance_policy": "fixed_max_over_orbit_and_multiview",
+        "shader": args.shader,
+        "background": list(args.background),
+        "smooth_iterations": args.smooth_iterations,
+        "require_vertex_colors": args.require_vertex_colors,
+        "vertex_colors_srgb": args.vertex_colors_srgb,
+        "multiview_yaws_degrees": list(args.multiview_yaws),
+        "orbit_mode": args.orbit_mode,
+        "orbit_span_degrees": args.orbit_span,
+        "scene_interpretation": (
+            "open_world_accessibility_surface_review"
+            if args.orbit_mode == "front_arc"
+            else "full_object_turntable"
+        ),
+    }
+    result = render_outputs(
+        mesh_path,
+        output_dir,
+        width=args.width,
+        height=args.height,
+        frames=args.frames,
+        fps=args.fps,
+        fov=args.fov,
+        elevation=args.elevation,
+        distance_scale=args.distance_scale,
+        shader=args.shader,
+        background=args.background,
+        smooth_iterations=args.smooth_iterations,
+        multiview_yaws=args.multiview_yaws,
+        orbit_mode=args.orbit_mode,
+        orbit_span=args.orbit_span,
+        require_vertex_colors=args.require_vertex_colors,
+        vertex_colors_srgb=args.vertex_colors_srgb,
+        cpu_fallback=args.cpu_fallback,
+    )
+    manifest = build_render_manifest(
+        mesh_path=mesh_path,
+        output_dir=output_dir,
+        sample_id=sample_id,
+        category=category,
+        render_settings=render_settings,
+        render_result=result,
+        environment_evidence=environment_evidence,
+        cpu_fallback=args.cpu_fallback,
+    )
+    write_json(output_dir / "manifest.json", manifest)
+    print(
+        json.dumps(
+            {
+                "status": "rendered",
+                "sample_id": sample_id,
+                "output_dir": str(output_dir),
+                "cpu_fallback_explicit": args.cpu_fallback,
+                "hardware_acceleration_status": manifest["renderer"][
+                    "hardware_acceleration_status"
+                ],
+            },
+            ensure_ascii=False,
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/sanitize_log_stream.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Filter a text stream so Slurm logs do not expose local identity details."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from accesspath3r.privacy import sanitize_text  # noqa: E402
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--project-root", type=Path, required=True)
+    parser.add_argument("--output-root", type=Path, default=None)
+    parser.add_argument("--sensitive-path", action="append", default=[])
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    for chunk in sys.stdin:
+        sys.stdout.write(
+            sanitize_text(
+                chunk,
+                project_root=args.project_root,
+                output_root=args.output_root,
+                sensitive_paths=args.sensitive_path,
+            )
+        )
+        sys.stdout.flush()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/sanitize_output_metadata.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""Remove workstation identity and absolute prefixes from text metadata."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+import tempfile
+from pathlib import Path
+
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from accesspath3r.privacy import sanitize_text  # noqa: E402
+
+
+TEXT_SUFFIXES = {".err", ".json", ".jsonl", ".log", ".md", ".out", ".txt"}
+
+
+def sanitize_file(
+    path: Path,
+    *,
+    project_root: Path,
+    output_root: Path,
+    sensitive_paths: list[str],
+) -> bool:
+    try:
+        original = path.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return False
+    sanitized = sanitize_text(
+        original,
+        project_root=project_root,
+        output_root=output_root,
+        sensitive_paths=sensitive_paths,
+    )
+    if sanitized == original:
+        return False
+
+    original_mode = path.stat().st_mode & 0o7777
+    file_descriptor, temporary_name = tempfile.mkstemp(
+        prefix=f".{path.name}.",
+        suffix=".tmp",
+        dir=path.parent,
+    )
+    try:
+        os.fchmod(file_descriptor, original_mode)
+        with os.fdopen(file_descriptor, "w", encoding="utf-8") as handle:
+            handle.write(sanitized)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary_name, path)
+    except BaseException:
+        try:
+            os.unlink(temporary_name)
+        except OSError:
+            pass
+        raise
+    return True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--root", type=Path, required=True)
+    parser.add_argument("--project-root", type=Path, required=True)
+    parser.add_argument("--sensitive-path", action="append", default=[])
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    if args.root.is_file():
+        paths = [args.root]
+        output_root = args.root.parent
+    elif args.root.is_dir():
+        paths = args.root.rglob("*")
+        output_root = args.root
+    else:
+        return 0
+    for path in paths:
+        if path.is_file() and path.suffix.lower() in TEXT_SUFFIXES:
+            sanitize_file(
+                path,
+                project_root=args.project_root,
+                output_root=output_root,
+                sensitive_paths=args.sensitive_path,
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/train_accessibility_amodal_adapter.py

@@ -0,0 +1,462 @@
+#!/usr/bin/env python3
+"""Train a small 2D hidden-mask adapter on the frozen accessibility split."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import random
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from PIL import Image, ImageDraw, ImageOps
+from torch.utils.data import DataLoader, Dataset
+
+
+def read_jsonl(path: Path) -> list[dict[str, Any]]:
+    return [json.loads(line) for line in path.read_text(encoding="utf-8").splitlines() if line.strip()]
+
+
+CANONICAL_CATEGORIES = ("curb_cut", "ramp", "stairs", "tactile_paving", "walkway")
+
+
+def row_image_path(row: dict[str, Any]) -> Path:
+    if row.get("image_path"):
+        path = Path(str(row["image_path"]))
+        if path.is_file():
+            return path
+    sample_dir = Path(row["sample_dir"])
+    candidates = [path for path in (sample_dir / "image.jpg", sample_dir / "image.png") if path.is_file()]
+    if len(candidates) != 1:
+        raise FileNotFoundError(f"Expected exactly one RGB image in {sample_dir}")
+    return candidates[0]
+
+
+def load_rgb(path: Path, size: int) -> np.ndarray:
+    # Ignore EXIF display orientation so RGB stays aligned with raw PNG masks.
+    image = Image.open(path).convert("RGB")
+    return np.asarray(image.resize((size, size), Image.Resampling.BILINEAR), dtype=np.float32) / 255.0
+
+
+def load_mask(path: Path, size: int | None = None) -> np.ndarray:
+    image = Image.open(path).convert("L")
+    if size is not None:
+        image = image.resize((size, size), Image.Resampling.NEAREST)
+    return np.asarray(image) > 127
+
+
+def category_planes(category: str, size: int) -> np.ndarray:
+    planes = np.zeros((len(CANONICAL_CATEGORIES), size, size), dtype=np.float32)
+    index = CANONICAL_CATEGORIES.index(category) if category in CANONICAL_CATEGORIES else -1
+    if index >= 0:
+        planes[index] = 1.0
+    return planes
+
+
+class AccessibilityMaskDataset(Dataset):
+    def __init__(self, rows: list[dict[str, Any]], size: int, augment: bool):
+        self.rows = rows
+        self.size = size
+        self.augment = augment
+
+    def __len__(self) -> int:
+        return len(self.rows)
+
+    def __getitem__(self, index: int) -> dict[str, Any]:
+        row = self.rows[index]
+        sample_dir = Path(row["sample_dir"])
+        rgb = load_rgb(row_image_path(row), self.size)
+        visible = load_mask(sample_dir / "target_visible.png", self.size)
+        obstacle = load_mask(sample_dir / "obstacle.png", self.size)
+        hidden = load_mask(sample_dir / "hidden.png", self.size)
+        if self.augment and random.random() < 0.5:
+            rgb = rgb[:, ::-1].copy()
+            visible = visible[:, ::-1].copy()
+            obstacle = obstacle[:, ::-1].copy()
+            hidden = hidden[:, ::-1].copy()
+        if self.augment:
+            gain = random.uniform(0.88, 1.12)
+            bias = random.uniform(-0.05, 0.05)
+            rgb = np.clip(rgb * gain + bias, 0.0, 1.0)
+        inputs = np.concatenate(
+            [
+                rgb.transpose(2, 0, 1),
+                visible[None].astype(np.float32),
+                obstacle[None].astype(np.float32),
+                category_planes(row["category"], self.size),
+            ],
+            axis=0,
+        )
+        return {
+            "input": torch.from_numpy(inputs.astype(np.float32)),
+            "hidden": torch.from_numpy(hidden[None].astype(np.float32)),
+            "obstacle": torch.from_numpy(obstacle[None].astype(np.float32)),
+            "sample_id": row["sample_id"],
+        }
+
+
+class ConvBlock(nn.Module):
+    def __init__(self, in_channels: int, out_channels: int):
+        super().__init__()
+        groups = min(8, out_channels)
+        self.block = nn.Sequential(
+            nn.Conv2d(in_channels, out_channels, 3, padding=1),
+            nn.GroupNorm(groups, out_channels),
+            nn.SiLU(),
+            nn.Conv2d(out_channels, out_channels, 3, padding=1),
+            nn.GroupNorm(groups, out_channels),
+            nn.SiLU(),
+        )
+
+    def forward(self, inputs: torch.Tensor) -> torch.Tensor:
+        return self.block(inputs)
+
+
+class TinyAmodalUNet(nn.Module):
+    def __init__(self, base: int = 24, in_channels: int = 5 + len(CANONICAL_CATEGORIES)):
+        super().__init__()
+        self.enc1 = ConvBlock(in_channels, base)
+        self.enc2 = ConvBlock(base, base * 2)
+        self.bottleneck = ConvBlock(base * 2, base * 4)
+        self.dec2 = ConvBlock(base * 4 + base * 2, base * 2)
+        self.dec1 = ConvBlock(base * 2 + base, base)
+        self.head = nn.Conv2d(base, 1, 1)
+
+    def forward(self, inputs: torch.Tensor) -> torch.Tensor:
+        first = self.enc1(inputs)
+        second = self.enc2(F.max_pool2d(first, 2))
+        bottleneck = self.bottleneck(F.max_pool2d(second, 2))
+        up_second = F.interpolate(bottleneck, size=second.shape[-2:], mode="bilinear", align_corners=False)
+        decoded_second = self.dec2(torch.cat([up_second, second], dim=1))
+        up_first = F.interpolate(decoded_second, size=first.shape[-2:], mode="bilinear", align_corners=False)
+        return self.head(self.dec1(torch.cat([up_first, first], dim=1)))
+
+
+def training_loss(logits: torch.Tensor, target: torch.Tensor, obstacle: torch.Tensor) -> torch.Tensor:
+    positive_weight = torch.tensor(8.0, device=logits.device)
+    bce = F.binary_cross_entropy_with_logits(logits, target, pos_weight=positive_weight)
+    probabilities = torch.sigmoid(logits)
+    intersection = (probabilities * target).sum(dim=(1, 2, 3))
+    denominator = probabilities.sum(dim=(1, 2, 3)) + target.sum(dim=(1, 2, 3))
+    dice_loss = 1.0 - ((2.0 * intersection + 1.0) / (denominator + 1.0)).mean()
+    outside_obstacle = (probabilities * (1.0 - obstacle)).mean()
+    return bce + dice_loss + 0.20 * outside_obstacle
+
+
+def iou(left: np.ndarray, right: np.ndarray, empty_value: float = 1.0) -> float:
+    union = left | right
+    return float((left & right).sum() / union.sum()) if np.any(union) else empty_value
+
+
+@torch.no_grad()
+def predict_probability(
+    model: nn.Module, row: dict[str, Any], size: int, device: torch.device
+) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    sample_dir = Path(row["sample_dir"])
+    image_path = row_image_path(row)
+    original = Image.open(image_path).convert("RGB")
+    width, height = original.size
+    rgb = load_rgb(image_path, size)
+    visible_small = load_mask(sample_dir / "target_visible.png", size)
+    obstacle_small = load_mask(sample_dir / "obstacle.png", size)
+    inputs = np.concatenate(
+        [
+            rgb.transpose(2, 0, 1),
+            visible_small[None].astype(np.float32),
+            obstacle_small[None].astype(np.float32),
+            category_planes(row["category"], size),
+        ],
+        axis=0,
+    )
+    logits = model(torch.from_numpy(inputs[None]).to(device)).sigmoid()[0, 0].cpu().numpy()
+    probability = np.asarray(
+        Image.fromarray(logits.astype(np.float32), mode="F").resize((width, height), Image.Resampling.BILINEAR)
+    ).copy()
+    visible = load_mask(sample_dir / "target_visible.png")
+    obstacle = load_mask(sample_dir / "obstacle.png")
+    hidden = load_mask(sample_dir / "hidden.png")
+    probability *= (obstacle & ~visible).astype(np.float32)
+    return probability, visible, obstacle, hidden
+
+
+@torch.no_grad()
+def evaluate_thresholds(
+    model: nn.Module,
+    rows: list[dict[str, Any]],
+    size: int,
+    device: torch.device,
+    thresholds: list[float],
+) -> tuple[float, dict[str, Any], dict[str, tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]]]:
+    cached = {row["sample_id"]: predict_probability(model, row, size, device) for row in rows}
+    reports = []
+    for threshold in thresholds:
+        sample_rows = []
+        for row in rows:
+            probability, visible, _, hidden = cached[row["sample_id"]]
+            predicted_hidden = probability >= threshold
+            predicted_amodal = visible | predicted_hidden
+            target_amodal = visible | hidden
+            sample_rows.append(
+                {
+                    "sample_id": row["sample_id"],
+                    "category": row["category"],
+                    "hidden_gt_pixels": int(hidden.sum()),
+                    "hidden_pred_pixels": int(predicted_hidden.sum()),
+                    "hidden_iou": iou(predicted_hidden, hidden),
+                    "amodal_iou": iou(predicted_amodal, target_amodal),
+                }
+            )
+        nonempty = [item for item in sample_rows if item["hidden_gt_pixels"] > 0]
+        reports.append(
+            {
+                "threshold": threshold,
+                "mean_hidden_iou_nonempty": float(np.mean([item["hidden_iou"] for item in nonempty])) if nonempty else 1.0,
+                "mean_amodal_iou": float(np.mean([item["amodal_iou"] for item in sample_rows])),
+                "negative_control_false_positive_pixels": int(
+                    sum(item["hidden_pred_pixels"] for item in sample_rows if item["hidden_gt_pixels"] == 0)
+                ),
+                "rows": sample_rows,
+            }
+        )
+    best = max(
+        reports,
+        key=lambda item: (
+            item["mean_hidden_iou_nonempty"],
+            item["mean_amodal_iou"],
+            -item["negative_control_false_positive_pixels"],
+        ),
+    )
+    return float(best["threshold"]), best, cached
+
+
+def save_mask(path: Path, mask: np.ndarray) -> None:
+    Image.fromarray(mask.astype(np.uint8) * 255, mode="L").save(path)
+
+
+def save_predictions(
+    output: Path,
+    rows: list[dict[str, Any]],
+    cached: dict[str, tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]],
+    threshold: float,
+) -> None:
+    output.mkdir(parents=True, exist_ok=True)
+    for row in rows:
+        sample_output = output / row["sample_id"]
+        sample_output.mkdir(parents=True, exist_ok=True)
+        probability, visible, _, _ = cached[row["sample_id"]]
+        predicted_hidden = probability >= threshold
+        save_mask(sample_output / "target_visible_mask.png", visible)
+        save_mask(sample_output / "hidden_completion_mask.png", predicted_hidden)
+        save_mask(sample_output / "amodal_accessibility_mask.png", visible | predicted_hidden)
+        Image.fromarray(np.clip(probability * 255.0, 0, 255).astype(np.uint8), mode="L").save(
+            sample_output / "hidden_probability.png"
+        )
+
+
+def color_overlay(image: Image.Image, masks: list[tuple[np.ndarray, tuple[int, int, int], float]]) -> Image.Image:
+    array = np.asarray(image.convert("RGB"), dtype=np.float32).copy()
+    for mask, color, alpha in masks:
+        array[mask] = array[mask] * (1.0 - alpha) + np.asarray(color) * alpha
+    return Image.fromarray(np.clip(array, 0, 255).astype(np.uint8))
+
+
+def build_contact_sheet(
+    path: Path,
+    rows: list[dict[str, Any]],
+    cached: dict[str, tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]],
+    threshold: float,
+) -> None:
+    panel_size = (320, 180)
+    label_height = 30
+    sheet = Image.new("RGB", (panel_size[0] * 3, (panel_size[1] + label_height) * len(rows)), "white")
+    draw = ImageDraw.Draw(sheet)
+    for row_index, row in enumerate(rows):
+        image = Image.open(row_image_path(row)).convert("RGB")
+        probability, visible, obstacle, hidden = cached[row["sample_id"]]
+        predicted = probability >= threshold
+        panels = (
+            (row["sample_id"], image),
+            ("GT: green visible / blue hidden / red obstacle", color_overlay(image, [(visible, (20, 210, 70), 0.38), (hidden, (40, 100, 245), 0.72), (obstacle, (235, 40, 40), 0.25)])),
+            ("prediction: green visible / magenta hidden", color_overlay(image, [(visible, (20, 210, 70), 0.38), (predicted, (235, 40, 200), 0.75)])),
+        )
+        y = row_index * (panel_size[1] + label_height)
+        for column, (label, panel) in enumerate(panels):
+            x = column * panel_size[0]
+            draw.text((x + 5, y + 7), label, fill="black")
+            fitted = ImageOps.fit(panel, panel_size, method=Image.Resampling.LANCZOS)
+            sheet.paste(fitted, (x, y + label_height))
+    sheet.save(path, quality=92, subsampling=0)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--split", default="output/accessibility_training_split_v1")
+    parser.add_argument("--output", default="output/accessibility_amodal_adapter_v1")
+    parser.add_argument("--epochs", type=int, default=100)
+    parser.add_argument("--patience", type=int, default=25)
+    parser.add_argument("--batch-size", type=int, default=4)
+    parser.add_argument("--image-size", type=int, default=256)
+    parser.add_argument("--learning-rate", type=float, default=3e-4)
+    parser.add_argument("--num-workers", type=int, default=2)
+    parser.add_argument("--seed", type=int, default=20260623)
+    parser.add_argument("--device", choices=["auto", "cuda", "cpu"], default="auto")
+    args = parser.parse_args()
+
+    random.seed(args.seed)
+    np.random.seed(args.seed)
+    torch.manual_seed(args.seed)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(args.seed)
+    split = Path(args.split)
+    split_summary = json.loads((split / "summary.json").read_text(encoding="utf-8"))
+    train_rows = read_jsonl(split / "train.jsonl") + read_jsonl(split / "auxiliary_train.jsonl")
+    validation_rows = read_jsonl(split / "validation.jsonl")
+    test_rows = read_jsonl(split / "test.jsonl")
+    if any(row["tier"] == "gold" for row in train_rows):
+        raise RuntimeError("Gold sample detected in training rows")
+    selected_device = (
+        "cuda" if args.device == "auto" and torch.cuda.is_available()
+        else "cpu" if args.device == "auto"
+        else args.device
+    )
+    device = torch.device(selected_device)
+    if device.type == "cuda" and not torch.cuda.is_available():
+        raise RuntimeError("CUDA requested but unavailable")
+
+    output = Path(args.output)
+    output.mkdir(parents=True, exist_ok=True)
+    loader = DataLoader(
+        AccessibilityMaskDataset(train_rows, args.image_size, augment=True),
+        batch_size=args.batch_size,
+        shuffle=True,
+        num_workers=args.num_workers,
+        pin_memory=device.type == "cuda",
+        generator=torch.Generator().manual_seed(args.seed),
+    )
+    model = TinyAmodalUNet().to(device)
+    optimizer = torch.optim.AdamW(model.parameters(), lr=args.learning_rate, weight_decay=1e-4)
+    scaler = torch.amp.GradScaler("cuda", enabled=device.type == "cuda")
+    thresholds = [round(value, 2) for value in np.arange(0.20, 0.81, 0.05)]
+    best_score = (-1.0, -1.0)
+    best_epoch = -1
+    stale_epochs = 0
+    history = []
+    for epoch in range(1, args.epochs + 1):
+        model.train()
+        losses = []
+        for batch in loader:
+            inputs = batch["input"].to(device, non_blocking=True)
+            target = batch["hidden"].to(device, non_blocking=True)
+            obstacle = batch["obstacle"].to(device, non_blocking=True)
+            optimizer.zero_grad(set_to_none=True)
+            with torch.autocast(device_type=device.type, dtype=torch.float16, enabled=device.type == "cuda"):
+                logits = model(inputs)
+                loss = training_loss(logits, target, obstacle)
+            scaler.scale(loss).backward()
+            scaler.step(optimizer)
+            scaler.update()
+            losses.append(float(loss.detach().cpu()))
+        model.eval()
+        threshold, validation, _ = evaluate_thresholds(
+            model, validation_rows, args.image_size, device, thresholds
+        )
+        record = {
+            "epoch": epoch,
+            "train_loss": float(np.mean(losses)),
+            "validation_threshold": threshold,
+            "validation_hidden_iou_nonempty": validation["mean_hidden_iou_nonempty"],
+            "validation_amodal_iou": validation["mean_amodal_iou"],
+        }
+        history.append(record)
+        print(json.dumps(record, ensure_ascii=False), flush=True)
+        score = (validation["mean_hidden_iou_nonempty"], validation["mean_amodal_iou"])
+        if score > best_score:
+            best_score = score
+            best_epoch = epoch
+            stale_epochs = 0
+            torch.save(
+                {
+                    "model_state": model.state_dict(),
+                    "epoch": epoch,
+                    "validation_threshold": threshold,
+                    "validation_metrics": validation,
+                    "split_fingerprint": split_summary["fingerprint"],
+                    "architecture": "TinyAmodalUNet",
+                    "input_channels": [
+                        "rgb",
+                        "target_visible",
+                        "occluding_obstacle",
+                        *CANONICAL_CATEGORIES,
+                    ],
+                    "model_input_channels": 5 + len(CANONICAL_CATEGORIES),
+                    "pseudo_depth_supervision": False,
+                },
+                output / "best.pt",
+            )
+        else:
+            stale_epochs += 1
+        if stale_epochs >= args.patience:
+            break
+
+    checkpoint = torch.load(output / "best.pt", map_location=device, weights_only=False)
+    model.load_state_dict(checkpoint["model_state"])
+    model.eval()
+    threshold, validation_report, validation_cache = evaluate_thresholds(
+        model, validation_rows, args.image_size, device, thresholds
+    )
+    _, test_report, test_cache = evaluate_thresholds(
+        model, test_rows, args.image_size, device, [threshold]
+    )
+    save_predictions(output / "predictions" / "validation", validation_rows, validation_cache, threshold)
+    save_predictions(output / "predictions" / "test", test_rows, test_cache, threshold)
+    build_contact_sheet(output / "validation_contact_sheet.jpg", validation_rows, validation_cache, threshold)
+    build_contact_sheet(output / "test_contact_sheet.jpg", test_rows, test_cache, threshold)
+    (output / "history.jsonl").write_text(
+        "".join(json.dumps(row, ensure_ascii=False, sort_keys=True) + "\n" for row in history),
+        encoding="utf-8",
+    )
+    baseline = {
+        "validation_mean_amodal_iou_visible_only": float(
+            np.mean(
+                [
+                    iou(load_mask(Path(row["sample_dir"]) / "target_visible.png"), load_mask(Path(row["sample_dir"]) / "target_amodal.png"))
+                    for row in validation_rows
+                ]
+            )
+        ),
+        "validation_mean_hidden_iou_nonempty_visible_only": 0.0,
+    }
+    summary = {
+        "status": "complete",
+        "model": "small_2d_hidden_mask_adapter_not_original_amodal3d",
+        "best_epoch": best_epoch,
+        "epochs_run": len(history),
+        "threshold_selected_on_validation": threshold,
+        "split_fingerprint": split_summary["fingerprint"],
+        "training_real_silver_count": 0,
+        "training_strict_gt_count": len(read_jsonl(split / "train.jsonl")),
+        "training_annotation_tier": "human_reviewed_strict_gt",
+        "strict_gt_used_for_training": True,
+        "training_auxiliary_synthetic_silver_count": len(read_jsonl(split / "auxiliary_train.jsonl")),
+        "gold_used_for_training": False,
+        "pseudo_depth_supervision": False,
+        "baseline": baseline,
+        "validation": {key: value for key, value in validation_report.items() if key != "rows"},
+        "test": {key: value for key, value in test_report.items() if key != "rows"},
+        "validation_rows": validation_report["rows"],
+        "test_rows": test_report["rows"],
+    }
+    (output / "summary.json").write_text(
+        json.dumps(summary, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    print(json.dumps(summary, ensure_ascii=False, indent=2), flush=True)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/update_accessibility_inference_progress.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Atomically update the Accessibility3R inference status file.
+
+This helper deliberately uses only the Python standard library so it can run
+inside the existing Accessibility3D environment without adding a dependency.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+
+
+def now_iso() -> str:
+    return datetime.now().astimezone().isoformat(timespec="seconds")
+
+
+def load_existing(path: Path) -> dict:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (FileNotFoundError, json.JSONDecodeError, OSError):
+        return {}
+    return value if isinstance(value, dict) else {}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--path", type=Path, required=True)
+    parser.add_argument("--status", choices=("running", "completed", "failed"), required=True)
+    parser.add_argument("--stage-key")
+    parser.add_argument("--stage-label")
+    parser.add_argument("--percent", type=float)
+    parser.add_argument("--stage-end-percent", type=float)
+    parser.add_argument("--stage-expected-seconds", type=float)
+    parser.add_argument("--total-estimated-seconds", type=float)
+    parser.add_argument("--message")
+    parser.add_argument("--exit-code", type=int)
+    args = parser.parse_args()
+
+    path = args.path.expanduser().resolve()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    current = load_existing(path)
+    timestamp = now_iso()
+    current.setdefault("started_at", timestamp)
+    current["updated_at"] = timestamp
+    current["status"] = args.status
+
+    if args.stage_key is not None:
+        current["stage_key"] = args.stage_key
+        current["stage_started_at"] = timestamp
+    if args.stage_label is not None:
+        current["stage_label"] = args.stage_label
+    if args.percent is not None:
+        current["percent"] = max(0.0, min(100.0, args.percent))
+    if args.stage_end_percent is not None:
+        current["stage_end_percent"] = max(0.0, min(100.0, args.stage_end_percent))
+    if args.stage_expected_seconds is not None:
+        current["stage_expected_seconds"] = max(0.0, args.stage_expected_seconds)
+    if args.total_estimated_seconds is not None:
+        current["total_estimated_seconds"] = max(1.0, args.total_estimated_seconds)
+    if args.message is not None:
+        current["message"] = args.message
+    if args.exit_code is not None:
+        current["exit_code"] = args.exit_code
+
+    if args.status == "completed":
+        current.pop("failed_at", None)
+        current.pop("exit_code", None)
+        current["percent"] = 100.0
+        current["stage_end_percent"] = 100.0
+        current["completed_at"] = timestamp
+    elif args.status == "failed":
+        current.pop("completed_at", None)
+        current["failed_at"] = timestamp
+    else:
+        current.pop("completed_at", None)
+        current.pop("failed_at", None)
+        current.pop("exit_code", None)
+
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    temporary.write_text(
+        json.dumps(current, ensure_ascii=False, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    os.replace(temporary, path)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/validate_accessibility_reviewed_visible_workspace.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Validate and materialize one human-reviewed visible accessibility mask.
+
+This deliberately supports *visible-mask-only* review.  It does not upgrade a
+reviewed visible mask into amodal ground truth: the hidden/obstacle layers are
+still generated as review candidates by the normal pipeline.  The tool is
+used by the Slurm launcher before it bypasses SAM3 for a reviewed mask.
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+from PIL import Image, ImageOps
+
+
+def file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def read_json(path: Path) -> dict[str, Any]:
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def write_json(path: Path, value: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_suffix(path.suffix + ".tmp")
+    temporary.write_text(
+        json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    temporary.replace(path)
+
+
+def display_rgb(path: Path) -> Image.Image:
+    return ImageOps.exif_transpose(Image.open(path)).convert("RGB")
+
+
+def read_binary_mask(path: Path, size: tuple[int, int]) -> np.ndarray:
+    mask = ImageOps.exif_transpose(Image.open(path)).convert("L")
+    if mask.size != size:
+        raise ValueError(
+            f"Reviewed visible mask size {mask.size} does not match normalized source RGB {size}."
+        )
+    return np.asarray(mask) > 127
+
+
+def validate_workspace(
+    workspace: Path,
+    source_image: Path,
+    sample_id: str,
+    category: str,
+) -> tuple[dict[str, Any], np.ndarray, tuple[int, int]]:
+    """Validate the reviewer identity, provenance, category, and exact raster grid."""
+    metadata_path = workspace / "metadata.json"
+    target_path = workspace / "target_visible.png"
+    image_path = workspace / "image.png"
+    for path in (metadata_path, target_path, image_path):
+        if not path.is_file():
+            raise ValueError(f"Reviewed visible-mask workspace is missing {path.name}: {workspace}")
+    metadata = read_json(metadata_path)
+    errors: list[str] = []
+    if str(metadata.get("sample_id", "")) != sample_id:
+        errors.append("sample_id does not match the requested inference sample")
+    if str(metadata.get("category", "")) != category:
+        errors.append("category does not match the requested inference category")
+    if str(metadata.get("review_status", "")) != "approved":
+        errors.append("review_status must be approved")
+    if not bool(metadata.get("review_is_human", False)):
+        errors.append("review_is_human must be true")
+    if not bool(metadata.get("visible_confirmed", False)):
+        errors.append("visible_confirmed must be true")
+    if not str(metadata.get("annotator", "")).strip():
+        errors.append("approved review requires a non-empty annotator")
+    if bool(metadata.get("target_amodal_is_ground_truth", False)):
+        errors.append("visible-only workspace must not claim target_amodal ground truth")
+    source_hash = file_sha256(source_image)
+    recorded_hash = str(metadata.get("source_image_sha256", ""))
+    if not recorded_hash or recorded_hash != source_hash:
+        errors.append("source image SHA-256 does not match the reviewed workspace")
+    source = display_rgb(source_image)
+    workspace_image = Image.open(image_path).convert("RGB")
+    if workspace_image.size != source.size:
+        errors.append(
+            f"workspace normalized RGB size {workspace_image.size} does not match source {source.size}"
+        )
+    if errors:
+        raise ValueError("Invalid reviewed visible-mask workspace: " + "; ".join(errors))
+    target = read_binary_mask(target_path, source.size)
+    if not target.any():
+        raise ValueError("Reviewed visible target mask is empty")
+    return metadata, target, source.size
+
+
+def materialize_workspace(
+    workspace: Path,
+    source_image: Path,
+    sample_id: str,
+    category: str,
+    output_dir: Path,
+) -> dict[str, Any]:
+    metadata, target, size = validate_workspace(workspace, source_image, sample_id, category)
+    output_dir.mkdir(parents=True, exist_ok=True)
+    target_path = output_dir / "target_visible.png"
+    obstacle_path = output_dir / "obstacle.png"
+    Image.fromarray(target.astype(np.uint8) * 255, mode="L").save(target_path)
+    Image.fromarray(np.zeros(target.shape, dtype=np.uint8), mode="L").save(obstacle_path)
+    result = {
+        "schema_version": 1,
+        "source_kind": "human_reviewed_visible_mask_only",
+        "sample_id": sample_id,
+        "category": category,
+        "review_status": "approved",
+        "review_is_human": True,
+        "visible_confirmed": True,
+        "annotator": str(metadata["annotator"]).strip(),
+        "reviewed_at_utc": metadata.get("reviewed_at_utc"),
+        "source_image_sha256": file_sha256(source_image),
+        "workspace_metadata_sha256": file_sha256(workspace / "metadata.json"),
+        "target_visible_sha256": file_sha256(target_path),
+        "target_visible_pixels": int(target.sum()),
+        "raster_size": {"width": size[0], "height": size[1]},
+        "hidden_and_obstacle_policy": "No reviewed hidden/obstacle layer was supplied; an empty obstacle candidate is passed to the adapter and all derived layers remain review candidates.",
+        "automatic_mask_is_ground_truth": False,
+        "target_amodal_is_ground_truth": False,
+        "created_at_utc": datetime.now(timezone.utc).isoformat(),
+    }
+    write_json(output_dir / "metadata.json", result)
+    return result
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--workspace", required=True)
+    parser.add_argument("--image", required=True)
+    parser.add_argument("--sample-id", required=True)
+    parser.add_argument("--category", required=True, choices=("curb_cut", "ramp", "stairs", "tactile_paving", "walkway"))
+    parser.add_argument("--output-dir", required=True)
+    args = parser.parse_args()
+    result = materialize_workspace(
+        Path(args.workspace).expanduser().resolve(),
+        Path(args.image).expanduser().resolve(),
+        args.sample_id,
+        args.category,
+        Path(args.output_dir).expanduser().resolve(),
+    )
+    print(json.dumps(result, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())