py360convert

https://github.com/sunset1995/py360convert
Admin
py360convert is a Python library for converting between 360-degree image formats including cubemap,...
Tokens:6,070
Snippets:36
Trust Score:7.8
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install py360convert

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Install the package using pip.

```bash
pip install py360convert
```

--------------------------------

### Command Line Interface Examples

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Examples demonstrating the usage of the `convert360` command-line tool for various conversion tasks.

```APIDOC
## Command Line Interface Examples

### Equirectangular to Cubemap Conversion

```bash
convert360 e2c assets/example_input.png out.png --size 200
```

| Input Equirectangular | Output Cubemap |
| :---: | :----: |
| ![](assets/example_input.png) | ![](assets/example_e2c.png) |

### Cubemap to Equirectangular Conversion

```bash
convert360 c2e assets/example_e2c.png out.png --width 800 --height 400
```

| Input Cubemap | Output Equirectangular |
| :---: | :----: |
| ![](assets/example_e2c.png) | ![](assets/example_c2e.png) |

*Note: Blurring artifacts in polar regions may occur due to resampling.

### Equirectangular to Perspective Conversion

```bash
convert360 e2p assets/example_input.png out.png --width 300 --height 300 --yaw 120 --pitch 23
```

| Input Equirectangular | Output Perspective |
| :---: | :----: |
| ![](assets/example_input.png) | ![](assets/example_e2p.png) |

Use `convert360 -h` for detailed command-line options.
```

--------------------------------

### Convert 360 images via CLI

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Use the convert360 command line tool to perform projections between different formats.

```bash
convert360 e2c assets/example_input.png out.png --size 200
```

```bash
convert360 c2e assets/example_e2c.png out.png --width 800 --height 400
```

```bash
convert360 e2p assets/example_input.png out.png --width 300 --height 300 --yaw 120 --pitch 23
```

--------------------------------

### Command Line Interface Usage

Source: https://context7.com/sunset1995/py360convert/llms.txt

Direct access to conversion functions from the terminal for equirectangular to cubemap, cubemap to equirectangular, and perspective extraction.

```bash
# Equirectangular to Cubemap (e2c)
# Convert panorama to dice format cubemap with 200px faces
convert360 e2c input_panorama.png output_cubemap.png --size 200

# Convert to horizon format
convert360 e2c input_panorama.png output_cubemap.png --size 256 --format horizon

# With explicit dimensions and bicubic interpolation
convert360 e2c input.png output.png --height 768 --width 1024 --mode bicubic

# Cubemap to Equirectangular (c2e)
# Convert dice cubemap to 800x400 equirectangular
convert360 c2e input_cubemap.png output_equirec.png --height 400 --width 800

# Convert horizon format cubemap
convert360 c2e input_horizon.png output.png -h 512 -w 1024 --format horizon

# Equirectangular to Perspective (e2p)
# Extract 300x300 perspective view at yaw=120°, pitch=23°
convert360 e2p panorama.png perspective.png --width 300 --height 300 --yaw 120 --pitch 23

# Custom field of view and roll
convert360 e2p panorama.png output.png -w 640 -h 480 --h-fov 90 --v-fov 60 --yaw 45 --pitch 0 --roll 10

# Using nearest neighbor interpolation
convert360 e2p input.png output.png -w 640 -h 480 --mode nearest

# Get help
convert360 --help
convert360 e2c --help
convert360 e2p --help
```

--------------------------------

### Convert cubemap formats in Python

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Demonstrates how to convert between different cubemap representations such as dice, horizon, dict, and list formats.

```python
import numpy as np
from PIL import Image
import py360convert

cube_dice = np.array(Image.open('assets/demo_cube.png'))

# You can make conversion between supported cubemap format
cube_h = py360convert.cube_dice2h(cube_dice)  # the inverse is cube_h2dice
cube_dict = py360convert.cube_h2dict(cube_h)  # the inverse is cube_dict2h
cube_list = py360convert.cube_h2list(cube_h)  # the inverse is cube_list2h
print('cube_dice.shape:', cube_dice.shape)
print('cube_h.shape:', cube_h.shape)
print('cube_dict.keys():', cube_dict.keys())
print('cube_dict["F"].shape:', cube_dict["F"].shape)
print('len(cube_list):', len(cube_list))
print('cube_list[0].shape:', cube_list[0].shape)
```

--------------------------------

### Grayscale Image Conversion with py360convert

Source: https://context7.com/sunset1995/py360convert/llms.txt

Demonstrates handling of grayscale images. The library automatically processes 2D grayscale inputs to produce 2D grayscale outputs for various conversion types. Ensure images are loaded as NumPy arrays.

```python
import numpy as np
from PIL import Image
import py360convert

# Load grayscale equirectangular image
equirec_gray = np.array(Image.open('panorama.png').convert('L'))
print(f"Grayscale input shape: {equirec_gray.shape}")  # (height, width)

# Convert to cubemap - output is also grayscale
cubemap_gray = py360convert.e2c(equirec_gray, face_w=256, cube_format='dice')
print(f"Grayscale cubemap shape: {cubemap_gray.shape}")  # (768, 1024)

# Extract perspective view from grayscale panorama
perspective_gray = py360convert.e2p(
    equirec_gray,
    fov_deg=90,
    u_deg=0,
    v_deg=0,
    out_hw=(480, 640)
)
print(f"Grayscale perspective shape: {perspective_gray.shape}")  # (480, 640)

# Convert grayscale cubemap back to equirectangular
equirec_reconstructed = py360convert.c2e(cubemap_gray, h=512, w=1024)
print(f"Reconstructed shape: {equirec_reconstructed.shape}")  # (512, 1024)
```

--------------------------------

### Python API: Equirectangular to Perspective

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Generates a perspective image from an equirectangular image using the `e2p` function.

```APIDOC
## `e2p(e_img, fov_deg, u_deg, v_deg, out_hw, in_rot_deg=0, mode='bilinear')`

### Description
Take a perspective image from a given equirectangular image.

### Method
`py360convert.e2p`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **e_img** (Numpy array) - Required - Numpy array with shape `[H, W, C]` representing the input equirectangular image.
- **fov_deg** (int or tuple) - Required - Field of view in degrees. Can be a single integer for both horizontal and vertical FOV, or a tuple `(h_fov_deg, v_fov_deg)`.
- **u_deg** (float) - Required - Horizontal viewing angle in degrees. Negative values look left, positive values look right.
- **v_deg** (float) - Required - Vertical viewing angle in degrees. Negative values look down, positive values look up. Range is typically `[-90, 90]`.
- **out_hw** (tuple) - Required - Output image dimensions as `(height, width)`.
- **in_rot_deg** (float) - Optional - In-plane rotation in degrees. Defaults to 0.
- **mode** (str) - Optional - Interpolation method. Options: `'bilinear'` (default) or `'nearest'`.

### Request Example
```python
import numpy as np
from PIL import Image
import py360convert

equirectangular_image = np.array(Image.open('assets/example_input.png'))
perspective_image = py360convert.e2p(equirectangular_image, fov_deg=(90, 90), u_deg=0, v_deg=0, out_hw=(300, 300), mode='bilinear')
```

### Response
#### Success Response (200)
- **perspective_image** (Numpy array) - The generated perspective image.

#### Response Example
```python
# Example output shape
print(perspective_image.shape) # e.g., (300, 300, 3)
```
```

--------------------------------

### Python API: Equirectangular to Cubemap

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Converts an equirectangular image to a cubemap using the `e2c` function.

```APIDOC
## `e2c(e_img, face_w=256, mode='bilinear', cube_format='dice')`

### Description
Convert the given equirectangular image to a cubemap.

### Method
`py360convert.e2c`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **e_img** (NDArray) - Required - Numpy array with shape `[H, W, C]` representing the input equirectangular image.
- **face_w** (int) - Optional - The desired width (and height) of each face in the output cubemap. Defaults to 256.
- **mode** (str) - Optional - Interpolation method. See `c2e` for valid options. Defaults to `'bilinear'`.
- **cube_format** (str) - Optional - Specifies the desired format for the output cubemap. Options: `'dice'` (default), `'horizon'`, `'dict'`, or `'list'`.

### Request Example
```python
import numpy as np
from PIL import Image
import py360convert

equirectangular_image = np.array(Image.open('assets/example_input.png'))
cubemap_image = py360convert.e2c(equirectangular_image, face_w=256, mode='bilinear', cube_format='dice')
```

### Response
#### Success Response (200)
- **cubemap_image** (Numpy array or dict/list of arrays) - The converted cubemap image, in the format specified by `cube_format`.

#### Response Example
```python
# Example output shape for 'dice' format
print(cubemap_image.shape) # e.g., (768, 1024, 3)
```
```

--------------------------------

### Interpolation Modes for Resampling

Source: https://context7.com/sunset1995/py360convert/llms.txt

Configure resampling quality using various interpolation modes, ranging from nearest neighbor to biquintic.

```python
import numpy as np
from PIL import Image
import py360convert

equirec_img = np.array(Image.open('panorama.png'))

# Available interpolation modes (lowest to highest quality):
# - 'nearest' (order 0): Fastest, pixelated results
# - 'linear'/'bilinear' (order 1): Good balance of speed and quality
# - 'biquadratic'/'quadratic'/'quad' (order 2): Higher quality
# - 'bicubic'/'cubic' (order 3): High quality, slower
# - 'biquartic'/'quartic' (order 4): Very high quality
# - 'biquintic'/'quintic' (order 5): Highest quality, slowest

# Nearest neighbor - fastest
cubemap_nearest = py360convert.e2c(equirec_img, face_w=256, mode='nearest')

# Bilinear - default, good quality
cubemap_bilinear = py360convert.e2c(equirec_img, face_w=256, mode='bilinear')
```

--------------------------------

### Python API: Cubemap Format Conversions

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Utility functions for converting between different cubemap formats (dice, horizon, list, dict).

```APIDOC
## Cubemap Format Conversion Utilities

### Description
These functions facilitate conversion between various representations of cubemap images.

### Methods
- `py360convert.cube_dice2h(cube_dice)`: Converts from 'dice' format to 'horizon' format.
- `py360convert.cube_h2dice(cube_h)`: Converts from 'horizon' format to 'dice' format.
- `py360convert.cube_h2dict(cube_h)`: Converts from 'horizon' format to 'dict' format.
- `py360convert.cube_dict2h(cube_dict)`: Converts from 'dict' format to 'horizon' format.
- `py360convert.cube_h2list(cube_h)`: Converts from 'horizon' format to 'list' format.
- `py360convert.cube_list2h(cube_list)`: Converts from 'list' format to 'horizon' format.

### Parameters
- Input parameters depend on the specific function, but generally involve numpy arrays representing cubemap faces in a particular format.

### Request Example
```python
import numpy as np
from PIL import Image
import py360convert

# Assuming cube_dice is loaded as a numpy array
cube_dice = np.array(Image.open('assets/demo_cube.png'))

# Convert dice to horizon
cube_h = py360convert.cube_dice2h(cube_dice)

# Convert horizon to dict
cube_dict = py360convert.cube_h2dict(cube_h)

# Convert dict back to horizon
reconstructed_cube_h = py360convert.cube_dict2h(cube_dict)

print('Original dice shape:', cube_dice.shape)
print('Horizon shape:', cube_h.shape)
print('Dict keys:', cube_dict.keys())
print('Reconstructed horizon shape:', reconstructed_cube_h.shape)
```

### Response
#### Success Response (200)
- The functions return numpy arrays or dictionaries/lists representing the cubemap in the target format.

#### Response Example
```
Original dice shape: (768, 1024, 3)
Horizon shape: (256, 1536, 3)
Dict keys: dict_keys(['F', 'R', 'B', 'L', 'U', 'D'])
Reconstructed horizon shape: (256, 1536, 3)
```
```

--------------------------------

### Extract Perspective Views from Equirectangular Images

Source: https://context7.com/sunset1995/py360convert/llms.txt

Use e2p to extract specific perspective views from a 360-degree panorama. Parameters allow for FOV, yaw, pitch, and roll adjustments.

```python
# v_deg: vertical angle (-90 to 90, negative=down, positive=up)
perspective = py360convert.e2p(
    equirec_img,
    fov_deg=90,                # Field of view in degrees (or tuple for h_fov, v_fov)
    u_deg=0,                   # Horizontal viewing angle (yaw)
    v_deg=0,                   # Vertical viewing angle (pitch)
    out_hw=(480, 640),         # Output height x width
    in_rot_deg=0,              # In-plane rotation (roll)
    mode='bilinear'
)
print(f"Perspective shape: {perspective.shape}")  # Output: (480, 640, 3)

# Extract view looking 120° right and 23° up
perspective_angled = py360convert.e2p(
    equirec_img,
    fov_deg=60,
    u_deg=120,                 # Look right 120 degrees
    v_deg=23,                  # Look up 23 degrees
    out_hw=(300, 300),
    mode='bilinear'
)

# Different horizontal and vertical field of view
perspective_wide = py360convert.e2p(
    equirec_img,
    fov_deg=(120, 90),         # (horizontal_fov, vertical_fov)
    u_deg=-45,                 # Look left 45 degrees
    v_deg=-15,                 # Look down 15 degrees
    out_hw=(480, 640),
    in_rot_deg=10              # Rotate view 10 degrees counter-clockwise
)

# Save result
Image.fromarray(perspective).save('perspective_output.png')
```

--------------------------------

### Python API: Cubemap to Equirectangular

Source: https://github.com/sunset1995/py360convert/blob/master/README.md

Converts a cubemap image to an equirectangular image using the `c2e` function.

```APIDOC
## `c2e(cubemap, h, w, cube_format='dice', mode='bilinear')`

### Description
Convert the given cubemap to equirectangular.

### Method
`py360convert.c2e`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **cubemap** (Numpy array or list/dict of numpy arrays) - Required - The input cubemap image data. The format is determined by `cube_format`.
- **h** (int) - Required - The desired height of the output equirectangular image.
- **w** (int) - Required - The desired width of the output equirectangular image.
- **cube_format** (str) - Optional - Specifies the format of the input `cubemap`. Options: `'dice'` (default), `'horizon'`, `'dict'`, or `'list'`.
    - `'dice'`: A numpy array with shape `(1024, 768)`.
    - `'horizon'`: A numpy array with shape `(1536, 256)`.
    - `'list'`: A list containing 6 numpy arrays, each of shape `(256, 256)`.
    - `'dict'`: A dictionary with keys `'F', 'R', 'B', 'L', 'U', 'D'`, each mapping to a numpy array of shape `(256, 256)`.
- **mode** (str) - Optional - Interpolation method. Valid options: "nearest", "linear", "bilinear" (default), "biquadratic", "quadratic", "bicubic", "cubic", "biquartic", "quartic", "biquintic", "quintic".

### Request Example
```python
import numpy as np
from PIL import Image
import py360convert

cube_dice = np.array(Image.open('assets/demo_cube.png'))
equirectangular_image = py360convert.c2e(cube_dice, h=400, w=800, cube_format='dice', mode='bilinear')
```

### Response
#### Success Response (200)
- **equirectangular_image** (Numpy array) - The converted equirectangular image.

#### Response Example
```python
# Example output shape (actual image data not shown)
print(equirectangular_image.shape) # e.g., (400, 800, 3)
```
```

--------------------------------

### Convert Cubemap to Equirectangular

Source: https://context7.com/sunset1995/py360convert/llms.txt

Converts cubemap images back to equirectangular format. The output width must be a multiple of 8.

```python
import numpy as np
from PIL import Image
import py360convert

# Load cubemap image in dice format
cubemap_img = np.array(Image.open('cubemap_dice.png'))

# Convert dice format cubemap to equirectangular
equirec = py360convert.c2e(cubemap_img, h=512, w=1024, mode='bilinear', cube_format='dice')
print(f"Equirectangular shape: {equirec.shape}")  # Output: (512, 1024, 3)

# Convert from horizon format
cubemap_horizon = np.array(Image.open('cubemap_horizon.png'))
equirec_from_horizon = py360convert.c2e(cubemap_horizon, h=512, w=1024, cube_format='horizon')

# Convert from list format
cubemap_list = [np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8) for _ in range(6)]
equirec_from_list = py360convert.c2e(cubemap_list, h=512, w=1024, cube_format='list')

# Convert from dict format with named faces
cubemap_dict = {
    'F': np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8),  # Front
    'R': np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8),  # Right
    'B': np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8),  # Back
    'L': np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8),  # Left
    'U': np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8),  # Up
    'D': np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8),  # Down
}
equirec_from_dict = py360convert.c2e(cubemap_dict, h=512, w=1024, cube_format='dict')

# Save result
Image.fromarray(equirec).save('equirectangular_output.png')
```

--------------------------------

### Extract Perspective View

Source: https://context7.com/sunset1995/py360convert/llms.txt

Extracts a perspective view from an equirectangular panorama using viewing angles and field of view.

```python
import numpy as np
from PIL import Image
import py360convert

# Load equirectangular panorama
equirec_img = np.array(Image.open('panorama.png'))

# Extract perspective view looking straight ahead
# u_deg: horizontal angle (-180 to 180, negative=left, positive=right)
```

--------------------------------

### Convert Equirectangular to Cubemap (Bicubic)

Source: https://context7.com/sunset1995/py360convert/llms.txt

Converts an equirectangular image to a cubemap using the bicubic interpolation mode for high quality. OpenCV acceleration is automatically used when available for bicubic mode.

```python
cubemap_bicubic = py360convert.e2c(equirec_img, face_w=256, mode='bicubic')
```

--------------------------------

### Convert Equirectangular to Cubemap

Source: https://context7.com/sunset1995/py360convert/llms.txt

Converts an equirectangular image to various cubemap formats. Supports dice, horizon, list, and dictionary layouts.

```python
import numpy as np
from PIL import Image
import py360convert

# Load equirectangular panorama
equirec_img = np.array(Image.open('panorama.png'))

# Convert to cubemap in dice format (default)
# Each face will be 256x256 pixels
cubemap_dice = py360convert.e2c(equirec_img, face_w=256, mode='bilinear', cube_format='dice')
print(f"Dice format shape: {cubemap_dice.shape}")  # Output: (768, 1024, 3)

# Convert to horizon format (6 faces side-by-side)
cubemap_horizon = py360convert.e2c(equirec_img, face_w=256, cube_format='horizon')
print(f"Horizon format shape: {cubemap_horizon.shape}")  # Output: (256, 1536, 3)

# Convert to list format (list of 6 face arrays)
cubemap_list = py360convert.e2c(equirec_img, face_w=256, cube_format='list')
print(f"List format: {len(cubemap_list)} faces, each {cubemap_list[0].shape}")
# Output: List format: 6 faces, each (256, 256, 3)

# Convert to dict format with named faces
cubemap_dict = py360convert.e2c(equirec_img, face_w=256, cube_format='dict')
print(f"Dict keys: {cubemap_dict.keys()}")
# Output: Dict keys: dict_keys(['F', 'R', 'B', 'L', 'U', 'D'])

# Save dice format result
Image.fromarray(cubemap_dice).save('cubemap_output.png')
```
Tokens:
Raw