# 📷 PyTorch 360° Image Conversion Toolkit
[](https://pypi.org/project/pytorch360convert/)
## Overview
This PyTorch-based library provides powerful and differentiable image transformation utilities for converting between different panoramic image formats:
- **Equirectangular (360°) Images**
- **Cubemap Representations**
- **Perspective Projections**
Built as an improved PyTorch implementation of the original [py360convert](https://github.com/sunset1995/py360convert) project, this library offers flexible, CPU & GPU-accelerated functions.
<div align="left">
<img src="https://github.com/ProGamerGov/pytorch360convert/blob/main/examples/output_equirectangular.jpg?raw=true" width="710px">
</div>
* Equirectangular format
<div align="left">
<img src="https://github.com/ProGamerGov/pytorch360convert/blob/main/examples/output_cubic.jpg?raw=true" width="710px">
</div>
* Cubemap 'dice' format
## 🔧 Requirements
- Python 3.7+
- PyTorch
## 📦 Installation
You can easily install the library using pip:
```bash
pip install pytorch360convert
```
Or you can install it from source like this:
```bash
pip install torch
```
Clone the repository:
```bash
git clone https://github.com/ProGamerGov/pytorch360convert.git
cd pytorch360convert
pip install .
```
## 🚀 Key Features
- Lossless conversion between image formats.
- Supports different cubemap input formats (horizon, list, dict, dice).
- Configurable sampling modes (bilinear, nearest).
- CPU and torch.float16 support.
- GPU acceleration.
- Differentiable transformations for deep learning pipelines.
## 💡 Usage Examples
### Helper Functions
First we'll setup some helper functions:
```bash
pip install torchvision pillow
```
```python
import torch
from torchvision.transforms import ToTensor, ToPILImage
from PIL import Image
def load_image_to_tensor(image_path: str) -> torch.Tensor:
"""Load an image as a PyTorch tensor."""
return ToTensor()(Image.open(image_path).convert('RGB'))
def save_tensor_as_image(tensor: torch.Tensor, save_path: str) -> None:
"""Save a PyTorch tensor as an image."""
ToPILImage()(tensor).save(save_path)
```
### Equirectangular to Cubemap Conversion
Coverting equirectangular images into cubemaps is easy. For simplicitly, we'll use the 'dice' format, which places all cube faces into a single 4x3 grid image.
```python
from pytorch360convert import e2c
# Load equirectangular image
equi_image = load_image_to_tensor("360_panorama.jpg")
# Convert to cubemap (dice format)
cubemap = e2c(
equi_image, # CHW format
face_w=1024, # Width of each cube face
mode='bilinear', # Sampling interpolation
cube_format='dice' # Output cubemap layout
)
# Save cubemap faces
save_tensor_as_image(cubemap, "cubemap.jpg")
```
### Cubemap to Equirectangular Conversion
We can also convert cubemaps into equirectangular images, like so. Note that we use the same cubemap we created above and the same cubemap format used to make it.
```python
from pytorch360convert import c2e
# Load cubemap in 'dice' format
equi_image = load_image_to_tensor("cubemap.jpg")
# Convert cubemap back to equirectangular
equirectangular = c2e(
cubemap, # Cubemap tensor(s)
h=2048, # Output height
w=4096, # Output width
mode='bilinear', # Sampling interpolation
cube_format='dice' # Input cubemap layout
)
save_tensor_as_image(equirectangular, "equirectangular.jpg")
```
### Perspective Projection from Equirectangular
```python
from pytorch360convert import e2p
# Extract perspective view from equirectangular image
perspective_view = e2p(
equi_image, # Equirectangular image
fov_deg=(90, 60), # Horizontal and vertical FOV
u_deg=45, # Horizontal rotation
v_deg=15, # Vertical rotation
out_hw=(720, 1280), # Output image dimensions
mode='bilinear' # Sampling interpolation
)
save_tensor_as_image(perspective_view, "perspective.jpg")
```
## 📚 Basic Functions
### `e2c(e_img, face_w=256, mode='bilinear', cube_format='dice')`
Converts an equirectangular image to a cubemap projection.
- **Parameters**:
- `e_img` (torch.Tensor): Equirectangular CHW image tensor.
- `face_w` (int, optional): Cube face width. Default: `256`.
- `mode` (str, optional): Sampling interpolation mode. Options are `bilinear` and `nearest`. Default: `bilinear`
- `cube_format` (str, optional): The desired output cubemap format. Options are `dict`, `list`, `horizon`, `stack`, and `dice`. Default: `dice`
- `stack`: Stack of 6 faces (torch.Tensor), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.
- `list`: List of 6 faces (List[torch.Tensor]), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.
- `dict`: Dictionary with keys pointing to face tensors: (Dict[str, torch.Tensor]). Keys are: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`
- `dice`: A cubemap in a `dice` layout (`torch.Tensor`).
- `horizon`: A cubemap in a `horizon` layout (`torch.Tensor`).
- `channels_first` (bool, optional): Input cubemap channel format (CHW or HWC). Defaults to the PyTorch CHW standard of `True`.
- **Returns**: Cubemap representation of the input image as a tensor, list of tensors, or dict or tensors.
### `c2e(cubemap, h, w, mode='bilinear', cube_format='dice')`
Converts a cubemap projection to an equirectangular image.
- **Parameters**:
- `cubemap` (torch.Tensor, list of torch.Tensor, or dict of torch.Tensor): Cubemap image tensor, list of tensors, or dict of tensors. Note that tensors should be in the shape of: `CHW`. Inputs should match the corresponding `cube_format`.
- `h` (int, optional): Output image height. If set to None, `<cube_face_width> * 2` will be used. Default: `None`.
- `w` (int, optional): Output image width. If set to None, `<cube_face_width> * 4` will be used. Default: `None`.
- `mode` (str, optional): Sampling interpolation mode. Options are `bilinear` and `nearest`. Default: `bilinear`
- `cube_format` (str, optional): Input cubemap format. Options are `dict`, `list`, `horizon`, `stack`, and `dice`. Default: `dice`
- `stack`: Stack of 6 faces (torch.Tensor), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.
- `list`: List of 6 faces (List[torch.Tensor]), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.
- `dict`: Dictionary with keys pointing to face tensors: (Dict[str, torch.Tensor]). Keys are expected to be: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`
- `dice`: A cubemap in a `dice` layout (`torch.Tensor`).
- `horizon`: A cubemap in a `horizon` layout (`torch.Tensor`).
- `channels_first` (bool, optional): Input cubemap channel format (CHW or HWC). Defaults to the PyTorch CHW standard of `True`.
- **Returns**: Equirectangular projection of the input cubemap as a tensor.
### `e2p(e_img, fov_deg, u_deg, v_deg, out_hw, in_rot_deg=0, mode='bilinear')`
Extracts a perspective view from an equirectangular image.
- **Parameters**:
- `e_img` (torch.Tensor): Equirectangular CHW image tensor.
- `fov_deg` (float or tuple): Field of view in degrees. If using a tuple, adhere to the following format: (h_fov_deg, v_fov_deg)
- `u_deg` (float): Horizontal viewing angle in range [-pi, pi]. (- Left / + Right).
- `v_deg` (float): Vertical viewing angle in range [-pi/2, pi/2]. (- Down/ + Up).
- `out_hw` (tuple): Output image dimensions in the shape of `(height, width)`.
- `in_rot_deg` (float, optional): Inplane rotation angle. Default: 0
- `mode` (str, optional): Sampling interpolation mode. Options are `bilinear` and `nearest`. Default: `bilinear`
- `channels_first` (bool, optional): Input cubemap channel format (CHW or HWC). Defaults to the PyTorch CHW standard of `True`.
- **Returns**: Perspective view of the equirectangular image as a tensor.
## 🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## 🔬 Citation
If you use this library in your research or project, please refer to the included CITATION.cff file or cite it as follows:
### BibTeX
```bibtex
@misc{egan2024pytorch360convert,
title={PyTorch 360° Image Conversion Toolkit},
author={Egan, Ben},
year={2024},
publisher={GitHub},
howpublished={\url{https://github.com/ProGamerGov/pytorch360convert}}
}
```
### APA Style
```
Egan, B. (2024). PyTorch 360° Image Conversion Toolkit [Computer software]. GitHub. https://github.com/ProGamerGov/pytorch360convert
```
Raw data
{
"_id": null,
"home_page": "https://github.com/ProGamerGov/pytorch360convert",
"name": "pytorch360convert",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "360 degree, equirectangular, cubemap, image processing, PyTorch, photo sphere, spherical photo, vr photography, pano, 360 photo, 360, perspective",
"author": "Ben Egan",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/9c/7d/197c1a32af15c69fbbabfe320f119788cecc4193e634e8b30dd1984b5c7a/pytorch360convert-0.1.1.tar.gz",
"platform": null,
"description": "# \ud83d\udcf7 PyTorch 360\u00b0 Image Conversion Toolkit\n\n[](https://pypi.org/project/pytorch360convert/)\n\n\n## Overview\n\nThis PyTorch-based library provides powerful and differentiable image transformation utilities for converting between different panoramic image formats:\n\n- **Equirectangular (360\u00b0) Images** \n- **Cubemap Representations**\n- **Perspective Projections**\n\nBuilt as an improved PyTorch implementation of the original [py360convert](https://github.com/sunset1995/py360convert) project, this library offers flexible, CPU & GPU-accelerated functions.\n\n\n<div align=\"left\">\n <img src=\"https://github.com/ProGamerGov/pytorch360convert/blob/main/examples/output_equirectangular.jpg?raw=true\" width=\"710px\">\n</div>\n\n* Equirectangular format\n\n\n<div align=\"left\">\n <img src=\"https://github.com/ProGamerGov/pytorch360convert/blob/main/examples/output_cubic.jpg?raw=true\" width=\"710px\">\n</div>\n\n* Cubemap 'dice' format\n\n\n## \ud83d\udd27 Requirements\n\n- Python 3.7+\n- PyTorch\n\n\n## \ud83d\udce6 Installation\n\nYou can easily install the library using pip:\n\n```bash\npip install pytorch360convert\n```\n\nOr you can install it from source like this:\n\n```bash\npip install torch\n```\n\nClone the repository:\n\n```bash\ngit clone https://github.com/ProGamerGov/pytorch360convert.git\ncd pytorch360convert\npip install .\n```\n\n\n## \ud83d\ude80 Key Features\n\n- Lossless conversion between image formats.\n- Supports different cubemap input formats (horizon, list, dict, dice).\n- Configurable sampling modes (bilinear, nearest).\n- CPU and torch.float16 support.\n- GPU acceleration.\n- Differentiable transformations for deep learning pipelines.\n\n\n## \ud83d\udca1 Usage Examples\n\n\n### Helper Functions\n\nFirst we'll setup some helper functions:\n\n```bash\npip install torchvision pillow\n```\n\n\n```python\nimport torch\nfrom torchvision.transforms import ToTensor, ToPILImage\nfrom PIL import Image\n\ndef load_image_to_tensor(image_path: str) -> torch.Tensor:\n \"\"\"Load an image as a PyTorch tensor.\"\"\"\n return ToTensor()(Image.open(image_path).convert('RGB'))\n\ndef save_tensor_as_image(tensor: torch.Tensor, save_path: str) -> None:\n \"\"\"Save a PyTorch tensor as an image.\"\"\"\n ToPILImage()(tensor).save(save_path)\n\n```\n\n### Equirectangular to Cubemap Conversion\n\nCoverting equirectangular images into cubemaps is easy. For simplicitly, we'll use the 'dice' format, which places all cube faces into a single 4x3 grid image.\n\n```python\nfrom pytorch360convert import e2c\n\n# Load equirectangular image\nequi_image = load_image_to_tensor(\"360_panorama.jpg\")\n\n# Convert to cubemap (dice format)\ncubemap = e2c(\n equi_image, # CHW format\n face_w=1024, # Width of each cube face\n mode='bilinear', # Sampling interpolation\n cube_format='dice' # Output cubemap layout\n)\n\n# Save cubemap faces\nsave_tensor_as_image(cubemap, \"cubemap.jpg\")\n```\n\n### Cubemap to Equirectangular Conversion\n\nWe can also convert cubemaps into equirectangular images, like so. Note that we use the same cubemap we created above and the same cubemap format used to make it.\n\n```python\nfrom pytorch360convert import c2e\n\n# Load cubemap in 'dice' format\nequi_image = load_image_to_tensor(\"cubemap.jpg\")\n\n# Convert cubemap back to equirectangular\nequirectangular = c2e(\n cubemap, # Cubemap tensor(s)\n h=2048, # Output height\n w=4096, # Output width\n mode='bilinear', # Sampling interpolation\n cube_format='dice' # Input cubemap layout\n)\n\nsave_tensor_as_image(equirectangular, \"equirectangular.jpg\")\n```\n\n### Perspective Projection from Equirectangular\n\n```python\nfrom pytorch360convert import e2p\n\n# Extract perspective view from equirectangular image\nperspective_view = e2p(\n equi_image, # Equirectangular image\n fov_deg=(90, 60), # Horizontal and vertical FOV\n u_deg=45, # Horizontal rotation\n v_deg=15, # Vertical rotation\n out_hw=(720, 1280), # Output image dimensions\n mode='bilinear' # Sampling interpolation\n)\n\nsave_tensor_as_image(perspective_view, \"perspective.jpg\")\n```\n\n\n## \ud83d\udcda Basic Functions\n\n### `e2c(e_img, face_w=256, mode='bilinear', cube_format='dice')`\nConverts an equirectangular image to a cubemap projection.\n\n- **Parameters**:\n - `e_img` (torch.Tensor): Equirectangular CHW image tensor.\n - `face_w` (int, optional): Cube face width. Default: `256`.\n - `mode` (str, optional): Sampling interpolation mode. Options are `bilinear` and `nearest`. Default: `bilinear`\n - `cube_format` (str, optional): The desired output cubemap format. Options are `dict`, `list`, `horizon`, `stack`, and `dice`. Default: `dice`\n - `stack`: Stack of 6 faces (torch.Tensor), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.\n - `list`: List of 6 faces (List[torch.Tensor]), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.\n - `dict`: Dictionary with keys pointing to face tensors: (Dict[str, torch.Tensor]). Keys are: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`\n - `dice`: A cubemap in a `dice` layout (`torch.Tensor`).\n - `horizon`: A cubemap in a `horizon` layout (`torch.Tensor`).\n - `channels_first` (bool, optional): Input cubemap channel format (CHW or HWC). Defaults to the PyTorch CHW standard of `True`.\n\n- **Returns**: Cubemap representation of the input image as a tensor, list of tensors, or dict or tensors.\n\n### `c2e(cubemap, h, w, mode='bilinear', cube_format='dice')`\nConverts a cubemap projection to an equirectangular image.\n\n- **Parameters**:\n - `cubemap` (torch.Tensor, list of torch.Tensor, or dict of torch.Tensor): Cubemap image tensor, list of tensors, or dict of tensors. Note that tensors should be in the shape of: `CHW`. Inputs should match the corresponding `cube_format`.\n - `h` (int, optional): Output image height. If set to None, `<cube_face_width> * 2` will be used. Default: `None`.\n - `w` (int, optional): Output image width. If set to None, `<cube_face_width> * 4` will be used. Default: `None`.\n - `mode` (str, optional): Sampling interpolation mode. Options are `bilinear` and `nearest`. Default: `bilinear`\n - `cube_format` (str, optional): Input cubemap format. Options are `dict`, `list`, `horizon`, `stack`, and `dice`. Default: `dice`\n - `stack`: Stack of 6 faces (torch.Tensor), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.\n - `list`: List of 6 faces (List[torch.Tensor]), in the order of: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`.\n - `dict`: Dictionary with keys pointing to face tensors: (Dict[str, torch.Tensor]). Keys are expected to be: `['Front', 'Right', 'Back', 'Left', 'Top', 'Bottom']`\n - `dice`: A cubemap in a `dice` layout (`torch.Tensor`).\n - `horizon`: A cubemap in a `horizon` layout (`torch.Tensor`).\n - `channels_first` (bool, optional): Input cubemap channel format (CHW or HWC). Defaults to the PyTorch CHW standard of `True`.\n \n- **Returns**: Equirectangular projection of the input cubemap as a tensor.\n\n### `e2p(e_img, fov_deg, u_deg, v_deg, out_hw, in_rot_deg=0, mode='bilinear')`\nExtracts a perspective view from an equirectangular image.\n\n- **Parameters**:\n - `e_img` (torch.Tensor): Equirectangular CHW image tensor.\n - `fov_deg` (float or tuple): Field of view in degrees. If using a tuple, adhere to the following format: (h_fov_deg, v_fov_deg)\n - `u_deg` (float): Horizontal viewing angle in range [-pi, pi]. (- Left / + Right).\n - `v_deg` (float): Vertical viewing angle in range [-pi/2, pi/2]. (- Down/ + Up).\n - `out_hw` (tuple): Output image dimensions in the shape of `(height, width)`.\n - `in_rot_deg` (float, optional): Inplane rotation angle. Default: 0\n - `mode` (str, optional): Sampling interpolation mode. Options are `bilinear` and `nearest`. Default: `bilinear`\n - `channels_first` (bool, optional): Input cubemap channel format (CHW or HWC). Defaults to the PyTorch CHW standard of `True`.\n\n- **Returns**: Perspective view of the equirectangular image as a tensor.\n\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n\n## \ud83d\udd2c Citation\n\nIf you use this library in your research or project, please refer to the included CITATION.cff file or cite it as follows:\n\n### BibTeX\n```bibtex\n@misc{egan2024pytorch360convert,\n title={PyTorch 360\u00b0 Image Conversion Toolkit},\n author={Egan, Ben},\n year={2024},\n publisher={GitHub},\n howpublished={\\url{https://github.com/ProGamerGov/pytorch360convert}}\n}\n```\n\n### APA Style\n```\nEgan, B. (2024). PyTorch 360\u00b0 Image Conversion Toolkit [Computer software]. GitHub. https://github.com/ProGamerGov/pytorch360convert\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "360 degree image manipulation and conversion utilities for PyTorch.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/ProGamerGov/pytorch360convert"
},
"split_keywords": [
"360 degree",
" equirectangular",
" cubemap",
" image processing",
" pytorch",
" photo sphere",
" spherical photo",
" vr photography",
" pano",
" 360 photo",
" 360",
" perspective"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "062484ec3a6a9ceb7804efcc5c2f54c23fcc84916a7a3387b3d38327679959b7",
"md5": "2a6f9c4befb9b153da94571030cd25b8",
"sha256": "48e07e952f4ff26acb58d2a290fb16803da134e5e1992d00de3d5302d46639d1"
},
"downloads": -1,
"filename": "pytorch360convert-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a6f9c4befb9b153da94571030cd25b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 12147,
"upload_time": "2024-12-18T21:16:19",
"upload_time_iso_8601": "2024-12-18T21:16:19.996609Z",
"url": "https://files.pythonhosted.org/packages/06/24/84ec3a6a9ceb7804efcc5c2f54c23fcc84916a7a3387b3d38327679959b7/pytorch360convert-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c7d197c1a32af15c69fbbabfe320f119788cecc4193e634e8b30dd1984b5c7a",
"md5": "05d25bba28af8ae2d46ea26fbf1845e4",
"sha256": "f143814b478aa50201c723ca62d77be3d19832cc0e1c7c3657b90260f6304797"
},
"downloads": -1,
"filename": "pytorch360convert-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "05d25bba28af8ae2d46ea26fbf1845e4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 15273,
"upload_time": "2024-12-18T21:16:23",
"upload_time_iso_8601": "2024-12-18T21:16:23.607001Z",
"url": "https://files.pythonhosted.org/packages/9c/7d/197c1a32af15c69fbbabfe320f119788cecc4193e634e8b30dd1984b5c7a/pytorch360convert-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-18 21:16:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ProGamerGov",
"github_project": "pytorch360convert",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pytorch360convert"
}
JSON
