PanoSAM

SAM3 segmentation for equirectangular panorama images.

Handles perspective projection, coordinate conversion, and mask deduplication.

panosam-demo.mp4

Installation

pip install panosam[sam3]   # Recommended: includes SAM3 dependencies

Extra	Command	Use Case
(none)	pip install panosam	Bring your own engine
[sam3]	pip install panosam[sam3]	SAM3 segmentation
[viz]	pip install panosam[viz]	Visualization
[full]	pip install panosam[full]	All features

SAM3 requires HuggingFace authentication:

huggingface-cli login

Usage

import panosam as ps
from panosam.engines.sam3 import SAM3Engine

engine = SAM3Engine()
client = ps.PanoSAM(engine=engine, views=ps.PerspectivePreset.DEFAULT)
result = client.segment("panorama.jpg", prompt="car")

for mask in result.masks:
    print(f"{mask.label}: yaw={mask.center_yaw:.1f}, pitch={mask.center_pitch:.1f}")

result.save_json("results.panosam.json")

Custom Engine

Any class with a matching segment() method works:

class MyEngine:
    def segment(
        self,
        image: Image.Image,
        text_prompt: str,
        threshold: float = 0.5,
        mask_threshold: float = 0.5,
        simplify_tolerance: float = 0.005,
    ) -> list[ps.FlatMaskResult]:
        ...

client = ps.PanoSAM(engine=MyEngine())

Perspective Presets

Preset	FOV	Resolution	Perspectives
DEFAULT	45°	2048x2048	16
ZOOMED_IN	22.5°	1024x1024	32
ZOOMED_OUT	60°	2500x2500	12
WIDEANGLE	90°	2500x2500	8

Documentation

See yz3440.github.io/panosam for full API reference and examples.

License

MIT