pyequilib

0.5.8 verified Fri May 01 auth: no python

A Python library for equirectangular image processing with minimum dependencies. Current version 0.5.8 supports numpy and PyTorch tensors, providing transforms like equi2pers, pers2equi, equi2cube, cube2equi, and horizontal/vertical shift. Release cadence is irregular; last release Dec 2022.

pip install pyequilib

Common errors

error AttributeError: module 'equilib' has no attribute 'equi2pers' ↓

cause The library version is too old (<0.2.0) or incorrectly installed.

fix

Upgrade to the latest version: pip install --upgrade pyequilib

error ModuleNotFoundError: No module named 'torch' ↓

cause Attempting to use PyTorch-specific functions when PyTorch is not installed.

fix

Install PyTorch: pip install torch, or use numpy-only functions: from equilib.numpy import equi2pers

error ValueError: Unknown input type: <class 'list'> ↓

cause Functions expect numpy arrays or torch tensors, not lists.

fix

Convert input to numpy array: np.array(your_list)

Warnings

breaking In version 0.5.0, the signature of grid_sample changed significantly. If upgrading from older versions (e.g., 0.3.x), code relying on the old grid_sample arguments will break. ↓

fix Update calls to use the new grid_sample interface; see release notes for details.

deprecated Functions that automatically detect input type (numpy vs torch) may be deprecated in favour of explicit module imports from equilib.numpy or equilib.torch. ↓

fix Use from equilib.numpy import equi2pers or from equilib.torch import equi2pers for clarity and future compatibility.

gotcha Default clipping (clip_output=True) clamps output to [0,1] for float images. If your input has values outside that range, set clip_output=False. This is especially important for HDR or raw data. ↓

fix Pass clip_output=False to functions like equi2pers or equi2cube to disable clamping.

gotcha The coordinate system is z-axis up (right-hand rule). Older versions (pre-0.3.0) had z-axis down. This affects rotation directions. Ensure your yaw/pitch/roll match the z-up convention. ↓

fix Review the docs for the coordinate convention. For conversions from earlier versions, negate pitch or roll accordingly.

Imports

equi2pers
```
from equilib import equi2pers
```
Common mistake is importing from equilib.numpy or equilib.torch directly.
Equi2Pers
```
from equilib import Equi2Pers
```
Class-based API also available, same import path.

Quickstart

Converts an equirectangular image to a perspective (rectilinear) view. The rots and fovs are in degrees.

import numpy as np
from equilib import equi2pers

# Create a sample equirectangular image (height, width, channels)
equi_img = np.random.rand(512, 1024, 3).astype(np.float32)

# Parameters for perspective view
h_fov = 90  # horizontal field of view in degrees
v_fov = 60  # vertical field of view in degrees
yaw = 0     # rotation around y-axis
pitch = 0   # rotation around x-axis
roll = 0    # rotation around z-axis
height = 256
width = 256

# Generate perspective image
pers_img = equi2pers(
    equi_img,
    rots=[yaw, pitch, roll],  # in degrees
    fovs=[h_fov, v_fov],      # in degrees
    height=height,
    width=width,
)
print(pers_img.shape)  # (256, 256, 3)