Quick start

This page starts with one complete Stable result, then reveals the three lower levels that implement it. The examples use synthetic HWC float RGB so they run without downloading an image, model or checkpoint.

Install

Install the latest published package with:

python -m pip install panorai

This site follows main. APIs explicitly marked as belonging to the unreleased source line require an installed wheel built from that line until the next release is published. Development checkouts can use python -m pip install -e .. See API stability in 3.x before depending on an Experimental name.

Load the spherical image object

Real workflows normally begin with an owned container rather than an anonymous array:

from panorai import EquirectangularImage

panorama = EquirectangularImage.open("room_360.jpg")
print(panorama.size, panorama.mode)

The object provides immutable spherical resize, 3D rotate, tangent crop, registered filter and projection-aware paste operations. See the spherical image object tutorial for an executable progression and the design rationale for the precise differences from a planar Pillow image.

1. Run an application

SphericalSLIC is the smallest complete example: it validates configuration, runs intrinsic spherical segmentation and returns a typed result.

from panorai import EquirectangularImage
from panorai.applications import SphericalSLIC

panorama = EquirectangularImage.sample("spherical-grid", size=(36, 18))

application = SphericalSLIC(n_segments=8, max_num_iter=2)
labels = application(panorama)

assert labels.kind == "labels"
assert labels.values.shape == panorama.shape_hw
assert labels.grid.is_canonical_erp
assert labels.support.shape == labels.validity.shape == panorama.shape_hw

labels.values is an integer HW raster. labels.grid says where those values live, while labels.support and labels.validity answer different questions: whether geometry covers a sample and whether valid data contributed.

2. Reveal the composition

Every Pipeline-backed application can expose its lower-level form:

finer = application.with_params(n_segments=32)
pipeline = application.as_pipeline()
description = pipeline.describe()

assert application.n_segments == 8  # the original remains unchanged
assert finer.n_segments == 32
assert pipeline.interface == "panorai-spherical-pipeline/v1"
assert description["steps"][0]["stage"] == "OnSphere"

The same block also demonstrates immutable reconfiguration. Use the application while its behavior fits; move to Pipeline when a stage, branch or reconstruction policy must change.

3. Choose the next level

Continue according to the decision you need to own

Level	Choose it when	Continue
Applications	Parameters change, but the method does not	Configure and persist wrappers
Pipeline	Stages, branches, batching or fusion change	Compose direct and projected processing
Spherical Ops	The operation or neural layer itself changes	Apply sphere-aware operations
Geometry	Rays, projections or sampling policy change	Control geometry explicitly

4. Keep the contract visible

Before using real depth, labels or masks, read Data modalities. Labels and masks use nearest sampling. Continuous depth requires explicit validity and units. The mathematical convention is defined normatively in PanorAi canonical spherical geometry.