# Panorai
**Panorai** is a Python package for spherical (360°) image processing, specifically focusing on sampling, projection, forward/backward transformations, and unsharp masking for panoramic or spherical data. It provides a modular pipeline to handle various steps, including:
- Resizing input images
- Sampling tangent points on a sphere (e.g., cube-based, Fibonacci-based)
- Projecting spherical images into local tangential (rectilinear) planes
- Re-projecting these rectilinear images back into the equirectangular space
- Configuring and applying unsharp masking to sharpen the projected images
- Logging and comparing configuration results (e.g., MSE) via an automated test suite
This README will guide you through the repository structure, installation, usage, and testing of **Panorai**.
---
## Table of Contents
1. [Overview](#overview)
2. [Directory Structure](#directory-structure)
3. [Installation](#installation)
4. [Examples](#examples)
5. [Key Modules and Classes](#key-modules-and-classes)
6. [Running Tests](#running-tests)
7. [Extending Panorai](#extending-panorai)
8. [License](#license)
---
## Overview
**Panorai** is a Python library designed for advanced geometric transformations, projections, and sampling on spherical and equirectangular data. It provides a highly modular framework for implementing gnomonic projections, backward projections, and blending strategies, suitable for 360-degree image processing and panoramic data transformations.
---
## Directory Structure
```markdown
/
├── panorai/
│ ├── __pycache__/
│ ├── common/
│ │ ├── __pycache__/
│ │ ├── __init__.py
│ │ └── shared_config.py
│ ├── pipeline/
│ │ ├── __pycache__/
│ │ ├── utils/
│ │ │ ├── __pycache__/
│ │ │ ├── __init__.py
│ │ │ └── resizer.py
│ │ ├── __init__.py
│ │ ├── pipeline.py
│ │ ├── pipeline_data.py
│ │ └── pipeline_old.py
│ ├── projection/
│ │ ├── __pycache__/
│ │ ├── utils/
│ │ │ ├── __pycache__/
│ │ │ ├── __init__.py
│ │ │ ├── remapper.py
│ │ │ └── unsharp.py
│ │ ├── __init__.py
│ │ ├── projector.py
│ │ └── projector_deprecated.py
│ ├── readme/
│ │ └── gnomonic.md
│ ├── sampler/
│ │ ├── __pycache__/
│ │ ├── __init__.py
│ │ └── sampler.py
│ ├── __init__.py
├── panorai.egg-info/
│ ├── dependency_links.txt
│ ├── PKG-INFO
│ ├── SOURCES.txt
│ └── top_level.txt
├── tests/
│ ├── __pycache__/
│ └── test_config_params.py
├── .gitignore
├── best_configs_chart.png
├── requirements.txt
├── setup.py
└── test_results.db
```
### Notable Contents
- **panorai/**
Main package directory containing submodules:
- **pipeline/**: The pipeline logic for forward/backward projection and data handling, plus utility functions like `resizer`.
- **projection/**: Projector classes (e.g., `GnomonicProjector`) and remapping/unsharp utility code.
- **sampler/**: Sphere sampling strategies (cube, icosahedron, Fibonacci).
- **readme/**: Additional notes/documentation (e.g., gnomonic.md).
- **setup.py**
A setuptools-based installation script.
- **requirements.txt**
Lists dependencies needed to run the code (e.g., NumPy, OpenCV, etc.).
---
## Installation
1. Clone the Repository:
```bash
git clone https://github.com/yourusername/panorai.git
cd panorai
```
2. Install Dependencies:
```bash
pip install -r requirements.txt
```
3. Install Panorai (Editable Mode or Standard):
```bash
pip install -e .
# or
python setup.py install
```
---
## Examples
### 1. Data Preparation
Start by loading your input data, typically stored in an `.npz` file containing `rgb`, `depth`, and other channels.
```python
import numpy as np
from panorai.pipeline.pipeline_data import PipelineData
# Load data from an NPZ file
filename = 'path/to/sample.npz' # Replace with your file path
arr = np.load(filename)
rgb = arr['rgb'] # Shape: (H, W, 3)
depth = np.sqrt(np.sum(arr['z']**2, axis=-1))[:, :, None] # Shape: (H, W, 1)
xyz = arr['z'] # Shape: (H, W, 3)
# Create a PipelineData instance
data = PipelineData.from_dict({
"rgb": rgb,
"depth": depth,
"xyz_depth": xyz
})
```
### 2. Preprocessing Data
Adjust for shadow angle and optionally rotate the equirectangular image:
```python
from panorai.pipeline.utils.preprocess_eq import PreprocessEquirectangularImage
# Visualize the original data
import matplotlib.pyplot as plt
plt.imshow(data.data['rgb'])
plt.show()
# Preprocess the data (e.g., handle shadow angle)
data.preprocess(shadow_angle=30)
plt.imshow(data.data['rgb'])
plt.show()
```
### 3. Using Projections
#### 3.1. Forward Projection
Project equirectangular data into a gnomonic projection.
```python
from panorai.submodules.projections import ProjectionRegistry
# Access the gnomonic projection
proj = ProjectionRegistry.get_projection('gnomonic', return_processor=True)
# Perform forward projection
face = proj.forward(data.data['rgb'])
plt.imshow(face)
plt.show()
```
#### 3.2. Backward Projection
Reconstruct the equirectangular image from a projection:
```python
# Perform backward projection
eq_img = proj.backward(face)
plt.imshow(eq_img)
plt.show()
```
### 4. Using the ProjectionPipeline
The `ProjectionPipeline` provides a high-level API for projections.
```python
from panorai.pipeline.pipeline import ProjectionPipeline
# Initialize the pipeline
pipe = ProjectionPipeline(projection_name='gnomonic')
# Forward projection
face = pipe.project(data)
plt.imshow(face['rgb'].astype(np.uint8))
plt.show()
```
#### 4.1. Using Samplers
Use samplers to generate multiple projections (e.g., cube or icosahedron samplers):
```python
pipe = ProjectionPipeline(projection_name='gnomonic', sampler_name='CubeSampler')
faces = pipe.project(data)
# Visualize a specific face
plt.imshow(faces['point_1']['rgb'].astype(np.uint8))
plt.show()
```
#### 4.2. Blending Projections
Blend multiple projections into a seamless equirectangular image:
```python
# Reconstruct equirectangular image
reconstructed = pipe.backward(faces)
plt.imshow(reconstructed['stacked'])
plt.show()
```
#### 4.3. Custom Configurations
Modify the pipeline configuration to customize the behavior:
```python
pipe = ProjectionPipeline(projection_name='gnomonic', sampler_name='IcosahedronSampler')
faces = pipe.project(data, subdivisions=2, fov_deg=40)
reconstructed = pipe.backward(faces)
plt.imshow(reconstructed['stacked'])
plt.show()
```
---
## Key Modules and Classes
1. **PipelineData**
A container for storing and stacking multiple image channels (e.g., `rgb`, `depth`).
2. **ProjectionPipeline**
Manages the forward/backward transformations using a chosen sampler and projector.
3. **Samplers**
- CubeSampler: Tangent points for cube-based projections.
- IcosahedronSampler: Icosahedron-based tangent points.
- FibonacciSampler: Fibonacci sphere sampling for uniform distribution.
4. **ProjectionRegistry**
- Project that implements the projection modules
https://github.com/RobinsonGarcia/projections/tree/main
---
## Extending Panorai
- **Add new samplers**: Implement a new class inheriting from `Sampler` and register it in `SAMPLER_CLASSES`.
- **Add new projectors**: Implement a new class inheriting from `ProjectionStrategy` and add it to `PROJECTOR_CLASSES`.
- **HF integration to handle depth estimation**: Implement seamless integration with HF to load and run DA inference
---
## License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
---
## Contact
For questions or feedback, contact the maintainers:
- **Your Name**: rlsgarcia@icloud.com
- **GitHub**: [https://github.com/RobinsonGarcia](https://github.com/RobinsonGarcia)
---
Enjoy using Panorai for your panoramic image processing!
Raw data
{
"_id": null,
"home_page": "https://github.com/RobinsonGarcia/PanorAi",
"name": "panorai",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "panorama, image processing, projection, gnomonic, computer vision",
"author": "Robinson Luiz Souza Garcia",
"author_email": "rlsgarcia@icloud.com",
"download_url": "https://files.pythonhosted.org/packages/25/02/5204f18fd98abb666bac3c9b2c2aa0bcb21f1e653a9b8be9e708c3c97c59/panorai-1.1b0.tar.gz",
"platform": null,
"description": "# Panorai\n\n**Panorai** is a Python package for spherical (360\u00b0) image processing, specifically focusing on sampling, projection, forward/backward transformations, and unsharp masking for panoramic or spherical data. It provides a modular pipeline to handle various steps, including:\n\n- Resizing input images \n- Sampling tangent points on a sphere (e.g., cube-based, Fibonacci-based) \n- Projecting spherical images into local tangential (rectilinear) planes \n- Re-projecting these rectilinear images back into the equirectangular space \n- Configuring and applying unsharp masking to sharpen the projected images \n- Logging and comparing configuration results (e.g., MSE) via an automated test suite \n\nThis README will guide you through the repository structure, installation, usage, and testing of **Panorai**.\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview) \n2. [Directory Structure](#directory-structure) \n3. [Installation](#installation) \n4. [Examples](#examples) \n5. [Key Modules and Classes](#key-modules-and-classes) \n6. [Running Tests](#running-tests) \n7. [Extending Panorai](#extending-panorai) \n8. [License](#license)\n\n---\n\n## Overview\n\n**Panorai** is a Python library designed for advanced geometric transformations, projections, and sampling on spherical and equirectangular data. It provides a highly modular framework for implementing gnomonic projections, backward projections, and blending strategies, suitable for 360-degree image processing and panoramic data transformations.\n\n---\n\n## Directory Structure\n\n```markdown\n/\n\u251c\u2500\u2500 panorai/\n\u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u251c\u2500\u2500 common/\n\u2502 \u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 shared_config.py\n\u2502 \u251c\u2500\u2500 pipeline/\n\u2502 \u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2502 \u251c\u2500\u2500 utils/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 resizer.py\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 pipeline.py\n\u2502 \u2502 \u251c\u2500\u2500 pipeline_data.py\n\u2502 \u2502 \u2514\u2500\u2500 pipeline_old.py\n\u2502 \u251c\u2500\u2500 projection/\n\u2502 \u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2502 \u251c\u2500\u2500 utils/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2502 \u251c\u2500\u2500 remapper.py\n\u2502 \u2502 \u2502 \u2514\u2500\u2500 unsharp.py\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u251c\u2500\u2500 projector.py\n\u2502 \u2502 \u2514\u2500\u2500 projector_deprecated.py\n\u2502 \u251c\u2500\u2500 readme/\n\u2502 \u2502 \u2514\u2500\u2500 gnomonic.md\n\u2502 \u251c\u2500\u2500 sampler/\n\u2502 \u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2502 \u2514\u2500\u2500 sampler.py\n\u2502 \u251c\u2500\u2500 __init__.py\n\u251c\u2500\u2500 panorai.egg-info/\n\u2502 \u251c\u2500\u2500 dependency_links.txt\n\u2502 \u251c\u2500\u2500 PKG-INFO\n\u2502 \u251c\u2500\u2500 SOURCES.txt\n\u2502 \u2514\u2500\u2500 top_level.txt\n\u251c\u2500\u2500 tests/\n\u2502 \u251c\u2500\u2500 __pycache__/\n\u2502 \u2514\u2500\u2500 test_config_params.py\n\u251c\u2500\u2500 .gitignore\n\u251c\u2500\u2500 best_configs_chart.png\n\u251c\u2500\u2500 requirements.txt\n\u251c\u2500\u2500 setup.py\n\u2514\u2500\u2500 test_results.db\n```\n\n### Notable Contents\n\n- **panorai/** \n Main package directory containing submodules:\n \n - **pipeline/**: The pipeline logic for forward/backward projection and data handling, plus utility functions like `resizer`. \n - **projection/**: Projector classes (e.g., `GnomonicProjector`) and remapping/unsharp utility code. \n - **sampler/**: Sphere sampling strategies (cube, icosahedron, Fibonacci). \n - **readme/**: Additional notes/documentation (e.g., gnomonic.md). \n\n- **setup.py** \n A setuptools-based installation script.\n\n- **requirements.txt** \n Lists dependencies needed to run the code (e.g., NumPy, OpenCV, etc.).\n\n---\n\n## Installation\n\n1. Clone the Repository:\n ```bash\n git clone https://github.com/yourusername/panorai.git\n cd panorai\n ```\n\n2. Install Dependencies:\n ```bash\n pip install -r requirements.txt\n ```\n\n3. Install Panorai (Editable Mode or Standard):\n ```bash\n pip install -e .\n # or\n python setup.py install\n ```\n\n---\n\n## Examples\n\n### 1. Data Preparation\n\nStart by loading your input data, typically stored in an `.npz` file containing `rgb`, `depth`, and other channels.\n\n```python\nimport numpy as np\nfrom panorai.pipeline.pipeline_data import PipelineData\n\n# Load data from an NPZ file\nfilename = 'path/to/sample.npz' # Replace with your file path\narr = np.load(filename)\n\nrgb = arr['rgb'] # Shape: (H, W, 3)\ndepth = np.sqrt(np.sum(arr['z']**2, axis=-1))[:, :, None] # Shape: (H, W, 1)\nxyz = arr['z'] # Shape: (H, W, 3)\n\n# Create a PipelineData instance\ndata = PipelineData.from_dict({\n \"rgb\": rgb,\n \"depth\": depth,\n \"xyz_depth\": xyz\n})\n```\n\n### 2. Preprocessing Data\n\nAdjust for shadow angle and optionally rotate the equirectangular image:\n\n```python\nfrom panorai.pipeline.utils.preprocess_eq import PreprocessEquirectangularImage\n\n# Visualize the original data\nimport matplotlib.pyplot as plt\nplt.imshow(data.data['rgb'])\nplt.show()\n\n# Preprocess the data (e.g., handle shadow angle)\ndata.preprocess(shadow_angle=30)\nplt.imshow(data.data['rgb'])\nplt.show()\n```\n\n### 3. Using Projections\n\n#### 3.1. Forward Projection\n\nProject equirectangular data into a gnomonic projection.\n\n```python\nfrom panorai.submodules.projections import ProjectionRegistry\n\n# Access the gnomonic projection\nproj = ProjectionRegistry.get_projection('gnomonic', return_processor=True)\n\n# Perform forward projection\nface = proj.forward(data.data['rgb'])\nplt.imshow(face)\nplt.show()\n```\n\n#### 3.2. Backward Projection\n\nReconstruct the equirectangular image from a projection:\n\n```python\n# Perform backward projection\neq_img = proj.backward(face)\nplt.imshow(eq_img)\nplt.show()\n```\n\n### 4. Using the ProjectionPipeline\n\nThe `ProjectionPipeline` provides a high-level API for projections.\n\n```python\nfrom panorai.pipeline.pipeline import ProjectionPipeline\n\n# Initialize the pipeline\npipe = ProjectionPipeline(projection_name='gnomonic')\n\n# Forward projection\nface = pipe.project(data)\nplt.imshow(face['rgb'].astype(np.uint8))\nplt.show()\n```\n\n#### 4.1. Using Samplers\n\nUse samplers to generate multiple projections (e.g., cube or icosahedron samplers):\n\n```python\npipe = ProjectionPipeline(projection_name='gnomonic', sampler_name='CubeSampler')\nfaces = pipe.project(data)\n\n# Visualize a specific face\nplt.imshow(faces['point_1']['rgb'].astype(np.uint8))\nplt.show()\n```\n\n#### 4.2. Blending Projections\n\nBlend multiple projections into a seamless equirectangular image:\n\n```python\n# Reconstruct equirectangular image\nreconstructed = pipe.backward(faces)\nplt.imshow(reconstructed['stacked'])\nplt.show()\n```\n\n#### 4.3. Custom Configurations\n\nModify the pipeline configuration to customize the behavior:\n\n```python\npipe = ProjectionPipeline(projection_name='gnomonic', sampler_name='IcosahedronSampler')\nfaces = pipe.project(data, subdivisions=2, fov_deg=40)\nreconstructed = pipe.backward(faces)\nplt.imshow(reconstructed['stacked'])\nplt.show()\n```\n\n---\n\n## Key Modules and Classes\n\n1. **PipelineData** \n A container for storing and stacking multiple image channels (e.g., `rgb`, `depth`).\n\n\n2. **ProjectionPipeline** \n Manages the forward/backward transformations using a chosen sampler and projector.\n\n\n3. **Samplers** \n - CubeSampler: Tangent points for cube-based projections.\n - IcosahedronSampler: Icosahedron-based tangent points.\n - FibonacciSampler: Fibonacci sphere sampling for uniform distribution.\n\n4. **ProjectionRegistry** \n - Project that implements the projection modules\n https://github.com/RobinsonGarcia/projections/tree/main\n\n---\n\n## Extending Panorai\n\n- **Add new samplers**: Implement a new class inheriting from `Sampler` and register it in `SAMPLER_CLASSES`.\n- **Add new projectors**: Implement a new class inheriting from `ProjectionStrategy` and add it to `PROJECTOR_CLASSES`.\n- **HF integration to handle depth estimation**: Implement seamless integration with HF to load and run DA inference\n\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n---\n\n## Contact\n\nFor questions or feedback, contact the maintainers:\n\n- **Your Name**: rlsgarcia@icloud.com\n- **GitHub**: [https://github.com/RobinsonGarcia](https://github.com/RobinsonGarcia)\n\n---\n\nEnjoy using Panorai for your panoramic image processing!\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package for panoramic image projection and blending using Gnomonic (and other) projections.",
"version": "1.1b0",
"project_urls": {
"Bug Tracker": "https://github.com/RobinsonGarcia/PanorAi/issues",
"Documentation": "https://github.com/RobinsonGarcia/PanorAi/wiki",
"Homepage": "https://github.com/RobinsonGarcia/PanorAi",
"Source Code": "https://github.com/RobinsonGarcia/PanorAi"
},
"split_keywords": [
"panorama",
" image processing",
" projection",
" gnomonic",
" computer vision"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "251c6597396dad9fe3ae8cd0893a37cb85de4b2343708dcd1c7be9feac1d37a6",
"md5": "0af1c1be2a3d8d570cec124306c2e52b",
"sha256": "ad318cb1f3e9333e9773ee232f4ae576dfa64ce4f0c68d2e87688f435f850fa5"
},
"downloads": -1,
"filename": "panorai-1.1b0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0af1c1be2a3d8d570cec124306c2e52b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 52742,
"upload_time": "2025-01-21T01:07:04",
"upload_time_iso_8601": "2025-01-21T01:07:04.286932Z",
"url": "https://files.pythonhosted.org/packages/25/1c/6597396dad9fe3ae8cd0893a37cb85de4b2343708dcd1c7be9feac1d37a6/panorai-1.1b0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "25025204f18fd98abb666bac3c9b2c2aa0bcb21f1e653a9b8be9e708c3c97c59",
"md5": "656183b67140cba5d6b659e7b5319b8a",
"sha256": "d21d6a788140ed4d51dee45c2eb27e5e0bc4a84146c92776e15f0e1df9d536bd"
},
"downloads": -1,
"filename": "panorai-1.1b0.tar.gz",
"has_sig": false,
"md5_digest": "656183b67140cba5d6b659e7b5319b8a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 40822,
"upload_time": "2025-01-21T01:07:08",
"upload_time_iso_8601": "2025-01-21T01:07:08.264580Z",
"url": "https://files.pythonhosted.org/packages/25/02/5204f18fd98abb666bac3c9b2c2aa0bcb21f1e653a9b8be9e708c3c97c59/panorai-1.1b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-21 01:07:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RobinsonGarcia",
"github_project": "PanorAi",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "panorai"
}
JSON
