API Reference#

Top-Level API#

The main entry points are in the panodac module.

predict #

predict(image: Union[str, Path, ndarray, Image], model: str = 'outdoor-resnet101', device: Union[str, None] = None, fix_panorama_seam: bool = True) -> np.ndarray

Predict metric depth from any camera image.

Supports perspective, fisheye, and 360° panorama images. Models are automatically downloaded from HuggingFace on first use.

Parameters:

Name Type Description Default
image Union[str, Path, ndarray, Image]

Input image. Can be: - Path to image file (str or Path) - numpy array (H, W, 3) in RGB format, values 0-255 - PIL Image

 required
model str

Model to use. One of: - 'outdoor-resnet101' (default): Fast outdoor model - 'outdoor-swinl': High-quality outdoor model - 'indoor-resnet101': Fast indoor model - 'indoor-swinl': High-quality indoor model

 'outdoor-resnet101'
device Union[str, None]

Device to use ('cuda', 'mps', 'cpu', or None for auto-detect)

 None
fix_panorama_seam bool

If True (default), apply Poisson blending to correct left-right seam artifacts in ERP panorama depth outputs.

 True

Returns:

Type Description
ndarray

Depth map as numpy array (H, W) with metric depth in meters.
Example

import panodac depth = panodac.predict("photo.jpg") depth = panodac.predict("panorama.jpg", model="outdoor-swinl")

Source code in src/panodac/__init__.py 
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def predict(
    image: Union[str, Path, np.ndarray, Image.Image],
    model: str = "outdoor-resnet101",
    device: Union[str, None] = None,
    fix_panorama_seam: bool = True,
) -> np.ndarray:
    """Predict metric depth from any camera image.

    Supports perspective, fisheye, and 360° panorama images.
    Models are automatically downloaded from HuggingFace on first use.

    Args:
        image: Input image. Can be:
            - Path to image file (str or Path)
            - numpy array (H, W, 3) in RGB format, values 0-255
            - PIL Image
        model: Model to use. One of:
            - 'outdoor-resnet101' (default): Fast outdoor model
            - 'outdoor-swinl': High-quality outdoor model
            - 'indoor-resnet101': Fast indoor model
            - 'indoor-swinl': High-quality indoor model
        device: Device to use ('cuda', 'mps', 'cpu', or None for auto-detect)
        fix_panorama_seam: If True (default), apply Poisson blending to correct
            left-right seam artifacts in ERP panorama depth outputs.

    Returns:
        Depth map as numpy array (H, W) with metric depth in meters.

    Example:
        >>> import panodac
        >>> depth = panodac.predict("photo.jpg")
        >>> depth = panodac.predict("panorama.jpg", model="outdoor-swinl")
    """
    if model not in AVAILABLE_MODELS:
        raise ValueError(
            f"Unknown model '{model}'. Available models: {AVAILABLE_MODELS}"
        )

    # Get or create cached predictor
    cache_key = f"{model}:{device}:{fix_panorama_seam}"
    if cache_key not in _predictor_cache:
        _predictor_cache[cache_key] = DepthPredictor(
            model=model, device=device, fix_panorama_seam=fix_panorama_seam
        )

    predictor = _predictor_cache[cache_key]
    return predictor(image)

list_models #

list_models() -> list[str]

List all available pretrained models.

Returns:

Type Description
list[str]

List of model names that can be passed to predict()
Source code in src/panodac/__init__.py 
33
34
35
36
37
38
39
def list_models() -> list[str]:
    """List all available pretrained models.

    Returns:
        List of model names that can be passed to predict()
    """
    return AVAILABLE_MODELS.copy()

get_device #

get_device(device: Union[str, None] = None) -> torch.device

Get the best available device for inference.

Parameters:

Name Type Description Default
device Union[str, None]

Specific device to use ('cuda', 'mps', 'cpu'), or None for auto-detection.

 None

Returns:

Type Description
device

torch.device for inference
Source code in src/panodac/utils.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def get_device(device: Union[str, None] = None) -> torch.device:
    """Get the best available device for inference.

    Args:
        device: Specific device to use ('cuda', 'mps', 'cpu'), 
                or None for auto-detection.

    Returns:
        torch.device for inference
    """
    if device is not None:
        return torch.device(device)

    # Auto-detect best device
    if torch.backends.mps.is_available():
        return torch.device("mps")
    elif torch.cuda.is_available():
        return torch.device("cuda")
    return torch.device("cpu")

Panorama Seam Correction#

Panoramic (ERP) depth outputs can show a visible seam at the left/right boundary. panodac applies a Poisson-based seam correction by default when a panorama is detected. You can also call the seam blender directly.

fix_panorama_seam #

fix_panorama_seam(depth: ndarray, blend_width: int | None = None, *, anchor_strength: float = 0.001) -> np.ndarray

Convenience wrapper to fix ERP panorama depth seam artifacts.

Parameters:

Name Type Description Default
depth ndarray

(H, W) depth map.

 required
blend_width int | None

Half-width of the solve band. If None, auto-pick from width.

 None
Source code in src/panodac/seam_blending.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
def fix_panorama_seam(
    depth: np.ndarray,
    blend_width: int | None = None,
    *,
    anchor_strength: float = 1e-3,
) -> np.ndarray:
    """
    Convenience wrapper to fix ERP panorama depth seam artifacts.

    Args:
        depth: (H, W) depth map.
        blend_width: Half-width of the solve band. If None, auto-pick from width.
    """
    depth_f = _as_float32_depth(depth)
    H, W = depth_f.shape
    bw = _recommended_blend_width(W) if blend_width is None else int(blend_width)
    blender = PoissonSeamBlender(blend_width=bw, anchor_strength=float(anchor_strength))
    return blender.blend(depth_f)

Module Structure#

panodac/
├── __init__.py       # Top-level API (predict, list_models, get_device)
├── predictor.py      # DepthPredictor class
├── seam_blending.py  # Poisson seam correction for ERP panoramas
├── hub.py            # HuggingFace model download
├── utils.py          # Device detection, image loading
└── models/           # Neural network architectures
    ├── idisc.py      # IDisc model (perspective)
    ├── idisc_erp.py  # IDiscERP model (panorama)
    ├── encoder.py    # Image encoder
    └── backbones/    # ResNet, Swin Transformer

Submodules#

  • Predictor - DepthPredictor class for advanced usage
  • Seam Blending - Poisson seam correction utilities
  • Hub - Model download utilities