equilib

Key Capabilities

• Runtime Dependencies: Pure Python, requiring only numpy and torch.
• Hardware Support: Runs on both CPU and CUDA tensors.
• Processing Modes: Supports batched and mixed-precision processing.
• Input Flexibility: Automatically detects input types as either numpy.ndarray or torch.Tensor.
• Extensibility: Includes rotation-matrix creation and a customizable grid sampler.

The equilib library provides modular transforms to convert between different image projections. Each transform is available via both a class API (for object-oriented usage) and a func API (for functional usage).

Supported transforms:

• Cube2Equi / cube2equi: Cubemap $\rightarrow$ Equirectangular
• Equi2Cube / equi2cube: Equirectangular $\rightarrow$ Cubemap
• Equi2Equi / equi2equi: Equirectangular $\rightarrow$ Equirectangular
• Equi2Pers / equi2pers: Equirectangular $\rightarrow$ Perspective
• Pers2Equi / pers2equi: Perspective $\rightarrow$ Equirectangular

Every transform in equilib provides two equivalent ways to be used:

1. Class API: Instantiate a class (e.g., Equi2Pers) once with fixed configuration parameters. This is efficient if you are applying the same transformation settings to many different images.
2. Func API: Call a function (e.g., equi2pers) directly, passing the configuration on every call. This is useful for one-off transformations.

There is no behavioral difference between them; the Class API calls the Func API internally. Both APIs automatically detect if the input is a numpy.ndarray or a torch.Tensor and return the same type.

The equilib package provides a unified public API for all image projection transforms. Each transform is available in two formats:

1. Class variant: A class instance that can be configured and reused (e.g., equilib.Cube2Equi).
2. Function variant: A direct function call for quick, one-off transformations (e.g., equilib.cube2equi).

The grid_sample function allows you to choose between different sampling backends and specific implementation functions.

• Torch Backend: By default, it uses the native torch.nn.functional.grid_sample for high performance. A pure-torch implementation is also available for higher customizability.
• Numpy Backend: By default, it uses a pure-numpy implementation which is designed to be faster than scipy and more robust than cv2.remap.

You can override the default implementation by passing a specific function (like scipy.ndimage.map_coordinates or cv2.remap) to the override_func argument.

By default, equilib uses a right-handed XYZ global coordinate system where:

• The x-axis faces forward.
• The z-axis faces up.

Rotations are defined as counter-clockwise:

• roll: rotation about the x-axis.
• pitch: rotation about the y-axis.
• yaw: rotation about the z-axis.

If your application requires the z-axis to face down, you can flip the coordinate system by passing the z_down=True argument to any transform.

An equirectangular image is defined as any image with a 2:1 aspect ratio that captures a 360° field of view. Common resolutions used with equilib include:

• 2160s: 3840x1920
• 2880s: 5760x2880

To optimize processing speed, equilib uses grid sampling with specialized backends:

• Torch Backend: Uses torch.nn.functional.grid_sample by default. It supports CUDA tensors and batching. A customizable pure-torch implementation is also available.
• Numpy Backend: Uses a pure-numpy implementation designed to be faster than scipy and more robust than cv2.remap. You can override this behavior by passing a different function to the override_func argument (e.g., using scipy or cv2).

Input images must be in channel-first format. If your input is a standard image (HWC), you must transpose it to CHW or BxCxHxW before passing it to a transform.

Example for a single image: HWC $\rightarrow$ CHW using np.transpose(img, (2, 0, 1)).

import numpy as np
from PIL import Image

# Load and convert to CHW
equi_img = Image.open("./some_image.jpg")
equi_img = np.asarray(equi_img)
equi_img = np.transpose(equi_img, (2, 0, 1))  # HWC -> CHW

Install the pyequilib package using pip. Ensure you have Python >=3.9 and PyTorch >=2.8 installed as prerequisites.

pip install pyequilib

If you have installed the project in development mode using uv, you can run common tasks using uv run:

uv run pytest tests          # run the test suite
uv run ruff check .          # lint
uv run ruff format .         # format

Install the library using pip to begin processing equirectangular (360°) images in Python.

pip install pyequilib