panosam 0.1.1

PanoSAM is a Python library for running SAM3 segmentation on equirectangular panorama images with automatic perspective projection and deduplication.

PanoSAM

SAM3 segmentation for equirectangular panorama images.

Handles perspective projection, coordinate conversion, and mask deduplication.

https://github.com/user-attachments/assets/61a546ac-3fce-4c26-b87c-3e09b0e4c331

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