Metadata-Version: 2.4
Name: panorai
Version: 3.3.1
Summary: Spherical image processing, projection, sampling, and blending for panoramic computer vision.
Author-email: Robinson Luiz Souza Garcia <rlsgarcia@icloud.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/rlsgarcia-code/PanorAi
Project-URL: Documentation, https://rlsgarcia-code.github.io/PanorAi/
Project-URL: Issues, https://github.com/rlsgarcia-code/PanorAi/issues
Project-URL: Source, https://github.com/rlsgarcia-code/PanorAi
Keywords: 360 vision,computer vision,cubemap,equirectangular,gnomonic,panorama,projection,spherical images
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: opencv-python-headless<5,>=4.9
Requires-Dist: Pillow>=9
Requires-Dist: pydantic<3,>=2
Requires-Dist: PyYAML>=6
Requires-Dist: scikit-image>=0.22
Requires-Dist: scipy>=1.10
Provides-Extra: torch
Requires-Dist: torch<3,>=2.2; extra == "torch"
Provides-Extra: features
Requires-Dist: opencv-python-headless<5,>=4.9; extra == "features"
Provides-Extra: pycolmap
Requires-Dist: pycolmap>=3.13; extra == "pycolmap"
Provides-Extra: slam
Requires-Dist: rosbags<1,>=0.10; extra == "slam"
Provides-Extra: pcd
Requires-Dist: open3d>=0.18; extra == "pcd"
Provides-Extra: depth
Requires-Dist: torch<3,>=2.2; extra == "depth"
Requires-Dist: transformers>=4.39; extra == "depth"
Provides-Extra: depth-demo
Requires-Dist: gradio; extra == "depth-demo"
Requires-Dist: gradio_imageslider; extra == "depth-demo"
Requires-Dist: torch<3,>=2.2; extra == "depth-demo"
Requires-Dist: transformers>=4.39; extra == "depth-demo"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: setuptools-scm>=8; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: docs
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-nb; extra == "docs"
Requires-Dist: sphinx>=7; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Dynamic: license-file

# PanorAi

**Convention-safe spherical projection and computer vision for Python.**

PanorAi converts between equirectangular panoramas, gnomonic views, cubemaps,
and unit rays without hiding coordinate, interpolation, support, or validity
rules. NumPy is required; Torch and downstream integrations are optional.

## Choose a use case

| I want to… | Start here | Stability |
| --- | --- | --- |
| understand ERP pixels, rays, gnomonic views, cubemaps, samplers, and blenders | [Projection foundations](docs/tutorials/02_projection_foundations.md) | Stable geometry; compatibility samplers |
| run a model over 6 or arbitrary-N views and reconstruct the panorama | [Custom projection workflow](docs/tutorials/01_custom_pipeline.md) | Stable |
| extract SIFT, ORB, or AKAZE features and match panoramas | [Features and matching](docs/tutorials/03_features_and_matching.md) | Stable core |
| estimate spherical relative pose and triangulate two views | [Two-view geometry](docs/tutorials/04_two_view_geometry.md) | Experimental pose |
| reconstruct cameras and points from 3+ panoramas | [Multiview reconstruction](docs/tutorials/05_multiview_reconstruction.md) | Experimental |
| track a central ERP or calibrated central-fisheye sequence | [Spherical visual SLAM](docs/how_to/spherical_slam.rst) | Experimental |
| check exact coordinates, masks, interpolation, and cubemap ties | [Geometry v1 contract](docs/geometry-v1.md) | Stable 3.x |

## Install

```bash
pip install panorai
```

PanorAi supports Python 3.11–3.14 and OpenCV `>=4.9,<5`. Optional extras are
`panorai[torch]`, `panorai[pycolmap]`, `panorai[slam]`, and `panorai[pcd]`.

## Minimal projection

```python
import numpy as np
from panorai.geometry import GnomonicProjector, GnomonicSpec

erp_rgb = np.zeros((512, 1024, 3), dtype=np.float32)  # HWC, central ERP
spec = GnomonicSpec(
    center_lat_deg=10,
    center_lon_deg=30,
    hfov_deg=90,
    vfov_deg=70,
    output_shape_hw=(256, 320),
)
projector = GnomonicProjector(spec, interpolation="bilinear")
view = projector.project(erp_rgb)
restored = projector.back_project(view, output_shape_hw=erp_rgb.shape[:2])

assert view.data.shape == (256, 320, 3)
assert restored.support_mask.shape == erp_rgb.shape[:2]
```

`ProjectionResult` keeps values, geometric support, data validity, and valid
interpolation weight separate. Labels and masks use nearest sampling; floating
RGB and radial range may use bilinear sampling. Zero is data, never an implicit
invalid marker.

## What PanorAi owns

| Layer | Owner |
| --- | --- |
| spherical coordinates, projection, masks, provenance, view orchestration | PanorAi |
| SIFT, ORB, AKAZE, BFMatcher, and FLANN implementations | OpenCV |
| spherical five-point pose and global mapper | PanorAi, Experimental |
| optional COLMAP database/SfM route | PyCOLMAP/COLMAP |

The stable contracts are `panorai.geometry`, the modality-aware object
workflow, the supported blenders, and the `panorai.features` spherical
extraction/matching core. Relative pose in `panorai.estimators`, PyCOLMAP
export, multiview reconstruction in `panorai.reconstruction`, multiscale
routing, and `panorai.slam` remain clearly marked Experimental.

## Reference

- [Documentation home](docs/index.rst)
- [API stability tiers](docs/reference/stability.rst)
- [3.3.1 release checklist](docs/release-3.3.1-checklist.md)
- [Changelog](CHANGELOG.md)

PanorAi's distributed source is MIT licensed. Optional upstream projects and
models retain their own terms; see [LICENSE](LICENSE).
