API Reference#

Client API#

The PanoSAM class is the main entry point.

PanoSAM dataclass #

PanoSAM(engine: SegmentationEngine, views: ViewsInput = PerspectivePreset.DEFAULT, deduper: Optional[SphereMaskDeduplicationEngine] = None, default_options: SegmentationOptions = SegmentationOptions(), default_dedup: DedupOptions = DedupOptions())

High-level segmentation client for panoramas.

Parameters:

Name Type Description Default
engine SegmentationEngine

Segmentation engine (required). Use SAM3Engine or a custom engine conforming to the SegmentationEngine protocol.

 required
views ViewsInput

Perspective preset(s) or custom PerspectiveMetadata list.

 DEFAULT
deduper Optional[SphereMaskDeduplicationEngine]

Optional custom deduplication engine.

 None
default_options SegmentationOptions

Default segmentation options (threshold, mask_threshold, etc.).

 SegmentationOptions()
default_dedup DedupOptions

Default deduplication options (min_iou, use_union).

 DedupOptions()
Example

from panosam import PanoSAM, PerspectivePreset from panosam.engines.sam3 import SAM3Engine engine = SAM3Engine() ps = PanoSAM(engine=engine, views=PerspectivePreset.DEFAULT) result = ps.segment("panorama.jpg", "car")

SegmentationResult dataclass #

SegmentationResult(prompt: str, masks: Sequence[SphereMaskResult], image_path: Optional[str] = None, perspective_preset: Optional[str] = None, perspective_presets: Optional[Sequence[str]] = None)

Segmentation output plus metadata, with preview-tool-friendly JSON export.

save_json #

save_json(path: str) -> None

Save segmentation results in a JSON file suitable for the preview tool.

Source code in src/panosam/api/models.py 
84
85
86
87
def save_json(self, path: str) -> None:
    """Save segmentation results in a JSON file suitable for the preview tool."""
    with open(path, "w") as f:
        json.dump(self.to_dict(), f, indent=2)

PerspectivePreset #

Bases: str, Enum

Pre-defined perspective configurations for common object scales.

SegmentationOptions dataclass #

SegmentationOptions(threshold: float = 0.5, mask_threshold: float = 0.5, simplify_tolerance: float = 0.005)

Inference options passed to the underlying SAM engine.

DedupOptions dataclass #

DedupOptions(min_iou: float = 0.3, use_union: bool = True)

Deduplication options applied after multi-view segmentation.

Module Structure#

panosam/
├── api/              # Client API
│   ├── client.py     # PanoSAM
│   └── models.py     # SegmentationResult, options, SegmentationEngine protocol
├── engines/          # Segmentation engines (lazily imported)
│   └── sam3.py       # SAM3Engine (requires [sam3])
├── sam/              # Mask models
│   ├── models.py     # FlatMaskResult, SphereMaskResult
│   └── utils.py      # Visualization (requires [viz])
├── dedup/            # Deduplication
│   └── detection.py  # SphereMaskDeduplicationEngine
├── image/            # Panorama handling
│   ├── models.py     # PanoramaImage, PerspectiveMetadata
│   └── perspectives.py  # Presets, generate_perspectives()
└── geometry.py       # Coordinate conversion utilities

Submodules#