Component catalog¶

Use this catalog when you know the role a component must play, but not yet which PanorAi namespace owns it. It complements the API reference: the catalog answers what can I compose?, while the module pages document exact signatures and members.

PanorAi has four API levels, but more than four component roles. An Application is a configured end-to-end entry point. A Stage transforms one typed value inside a Pipeline. An operation transforms a spherical raster or lattice. An estimator turns observations into a geometric inference. An evaluator compares results under a frozen research protocol. Typed values carry the grid, support, validity, units and provenance between them. Geometry owns the coordinate transformations used by every level.

Choose by role¶

Applications

Complete tasks with the smallest configured surface.

Applications catalog

Pipeline Stages

Compose domain transitions, routing and reusable task steps.

Pipeline Stages catalog

Spherical Ops and layers

Process an ERP directly with NumPy objects or Torch layers.

Spherical Ops and layers catalog

Estimators and policies

Infer geometry and make quality decisions from observations.

Estimators and policies catalog

Typed data and results

Find the values exchanged between components.

Typed data and results catalog

Geometry

Work directly with pixels, rays, projectors and projection results.

Geometry catalog

Research evaluation

Measure spherical results with frozen, reproducible protocols.

Research evaluation catalog

Advanced subsystems

Navigate features, depth, semantics, reconstruction, graph and SLAM.

Subsystems and advanced surfaces

Quick chooser¶

Start from the smallest role that owns your decision¶
You need to…	Start with	Can run alone?	Typical composition
solve a complete supported task	Application	yes	Application exposes `as_pipeline()`
add, remove or reorder processing steps	Stage	yes, through `execute()`; normally in a Pipeline	`Pipeline(stage_a, stage_b)`
filter, resize, detect or pool on a sphere	Spherical operation	yes	direct call, `EquirectangularImage.filter()`, or `OnSphere`
infer pose or another model from observations	Estimator	yes	estimator Stage at the end of a Pipeline
preserve spatial meaning between steps	Typed data/result	it is data, not execution	Stage input/output and retained Pipeline values
compare results for research or promotion evidence	Research evaluator	yes	algorithm output plus independent reference evidence
control projections or coordinate conversions	Geometry	yes	used directly or behind higher-level components

How to read the catalog¶

Each curated table names the canonical import, stability, accepted input, returned output, execution domain and common composition. Stable means a 3.x compatibility promise. Experimental means public and tested but eligible to evolve; placing an Experimental component in a Stable Pipeline does not promote it.

The complete public-surface inventory is generated from contracts/public-api-surfaces-v2.json. It lists every audited public symbol, including advanced research surfaces and compatibility gateways. If a symbol is absent there, it is not part of the audited public API even if it can be imported from an implementation module.

The same manifest assigns every public surface to one or more roles and routes each role to a catalog, signature reference, concept and progressive guide. The registration tables at the start of the role pages are generated from that contract. CI rejects an unclassified public module, a surface without a role, a missing documentation route, or an incomplete Stable Application example/consumer contract.

Installed catalog¶

Consumers can inspect the same contract without cloning the repository or accessing the network:

from panorai.catalog import public_catalog

catalog = public_catalog()
slic = catalog.surface("spherical-applications-slic")
docs = catalog.documentation_for(
    "spherical-applications-slic",
    component="SphericalSLIC",
)

print(slic.tier, slic.public_symbols)
print(docs.primary.url)
print([link.url for link in docs.learn])
print([link.url for link in docs.help])

public_catalog() reads byte-identical JSON resources from the installed wheel and returns immutable records. learn contains role guides and concepts, help contains role references and catalogs, and context links the site home, global component catalog, and complete surface inventory.

The returned DocumentationSite deliberately reports scope="current-main" and versioned=False. The GitHub Pages URLs point to the current documentation for main; they are not immutable documentation for the installed package version. The catalog data and stability metadata, by contrast, always come from that installed distribution.

Composition model¶

The usual direction is:

Application
    └── Pipeline
          ├── Stage ── Spherical Op / estimator
          ├── Stage ── domain transition
          └── typed value or result
                 └── Geometry contract

This is not a restriction. Operations, estimators and Geometry functions can be used independently. Conversely, a custom Application may wrap a Pipeline assembled entirely from public Stages. See the extension contract before publishing a new wrapper or Stage.