py360convert

Use py360convert.c2e() to convert a cubemap image into an equirectangular format.

Parameters:

• cubemap: Numpy array or a collection (list/dict) of numpy arrays depending on cube_format.
• h: Output equirectangular height.
• w: Output equirectangular width.
• mode: Interpolation method. Valid options: "nearest", "linear", "bilinear", "biquadratic", "quadratic", "quad", "bicubic", "cubic", "biquartic", "quartic", "biquintic", "quintic".
• cube_format: Defines the input structure:
  • 'dice' (default): A single numpy array (e.g., shape 1024 x 768 for 256x256 faces).
  • 'horizon': A single numpy array (e.g., shape 1536 x 256).
  • 'list': A list containing 6 numpy arrays (one per face).
  • 'dict': A dict with keys 'F', 'R', 'B', 'L', 'U', 'D' (Front, Right, Back, Left, Up, Down).

import py360convert
# Example usage (conceptual)
py360convert.c2e(cubemap_array, h=400, w=800, cube_format='dice')

The library provides utility functions to transform cubemap representations between 'dice', 'horizon', 'dict', and 'list' formats.

Available Utilities:

• cube_dice2h(cubemap): Converts 'dice' format to 'horizon' format.
• cube_h2dice(cube_h): Converts 'horizon' format to 'dice' format.
• cube_h2dict(cube_h): Converts 'horizon' format to a dictionary of faces.
• cube_dict2h(cube_dict): Converts a dictionary of faces to 'horizon' format.
• cube_h2list(cube_h): Converts 'horizon' format to a list of 6 arrays.
• cube_list2h(cube_list): Converts a list of 6 arrays to 'horizon' format.

import numpy as np
from PIL import Image
import py360convert

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 horizon to list
cube_list = py360convert.cube_h2list(cube_h)

The e2p function converts an equirectangular image into a perspective (planar) image based on a specified field of view (FOV) and viewing angle. It supports both grayscale (2D) and color (3D) input images.

Parameters

• e_img: The input equirectangular image. Shape must be [H, W] or [H, W, C].
• fov_deg: The field of view in degrees. Can be a single scalar (applied to both axes) or a tuple (h_fov_deg, v_fov_deg).
• u_deg: Horizontal viewing angle (horizon) in degrees, in the range [-180, 180]. Negative values look left, positive values look right.
• v_deg: Vertical viewing angle in degrees, in the range [-90, 90]. Negative values look down, positive values look up.
• out_hw: A tuple (height, width) representing the desired output dimensions of the perspective image.
• in_rot_deg: (Optional) In-plane rotation in degrees.
• mode: (Optional) Interpolation mode. Supported values are `

The e2c() function converts an equirectangular image into various cubemap formats. It supports both 2D (grayscale) and 3D (color) input arrays.

Parameters

• e_img (NDArray): The input equirectangular image. Expected shape is [H, W] or [H, W, C].
• face_w (int): The length (width/height) of each individual face of the cubemap. Defaults to 256.
• mode (Literal["bilinear", "nearest"]): The interpolation mode used for sampling. Defaults to "bilinear".
• cube_format (Literal["horizon", "list", "dict", "dice"]): Specifies the structure of the returned cubemap.

Return Types based on cube_format

• "horizon" or "dice": Returns a single NDArray containing the combined cubemap data.
• "list": Returns a list[NDArray], where each element is a face of the cubemap.
• "dict": Returns a dict[str, NDArray], mapping face identifiers (e.g., 'front', 'back', etc.) to their respective face arrays.

import numpy as np
from py360convert import e2c

# Load or create an equirectangular image (H, W, C)
e_img = np.random.rand(512, 1024, 3).astype(np.float32)

# Convert to a single 'dice' format array
cubemap_dice = e2c(e_img, face_w=256, mode="bilinear", cube_format="dice")

# Convert to a dictionary of faces
cubemap_dict = e2c(e_img, face_w=256, cube_format="dict")