{"id":24325,"library":"pyequilib","title":"pyequilib","description":"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.","status":"active","version":"0.5.8","language":"python","source_language":"en","source_url":"https://github.com/haruishi43/equilib","tags":["equirectangular","360","perspective","cube-map","image-processing","numpy","pytorch"],"install":[{"cmd":"pip install pyequilib","lang":"bash","label":"Install from PyPI"}],"dependencies":[{"reason":"Core dependency for array operations","package":"numpy","optional":false},{"reason":"Optional for PyTorch tensor support","package":"torch","optional":true}],"imports":[{"note":"Common mistake is importing from equilib.numpy or equilib.torch directly.","symbol":"equi2pers","correct":"from equilib import equi2pers"},{"note":"Class-based API also available, same import path.","symbol":"Equi2Pers","correct":"from equilib import Equi2Pers"}],"quickstart":{"code":"import numpy as np\nfrom equilib import equi2pers\n\n# Create a sample equirectangular image (height, width, channels)\nequi_img = np.random.rand(512, 1024, 3).astype(np.float32)\n\n# Parameters for perspective view\nh_fov = 90  # horizontal field of view in degrees\nv_fov = 60  # vertical field of view in degrees\nyaw = 0     # rotation around y-axis\npitch = 0   # rotation around x-axis\nroll = 0    # rotation around z-axis\nheight = 256\nwidth = 256\n\n# Generate perspective image\npers_img = equi2pers(\n    equi_img,\n    rots=[yaw, pitch, roll],  # in degrees\n    fovs=[h_fov, v_fov],      # in degrees\n    height=height,\n    width=width,\n)\nprint(pers_img.shape)  # (256, 256, 3)","lang":"python","description":"Converts an equirectangular image to a perspective (rectilinear) view. The rots and fovs are in degrees."},"warnings":[{"fix":"Update calls to use the new grid_sample interface; see release notes for details.","message":"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.","severity":"breaking","affected_versions":"< 0.5.0"},{"fix":"Use from equilib.numpy import equi2pers or from equilib.torch import equi2pers for clarity and future compatibility.","message":"Functions that automatically detect input type (numpy vs torch) may be deprecated in favour of explicit module imports from equilib.numpy or equilib.torch.","severity":"deprecated","affected_versions":">= 0.5.0"},{"fix":"Pass clip_output=False to functions like equi2pers or equi2cube to disable clamping.","message":"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.","severity":"gotcha","affected_versions":">= 0.5.8"},{"fix":"Review the docs for the coordinate convention. For conversions from earlier versions, negate pitch or roll accordingly.","message":"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.","severity":"gotcha","affected_versions":">= 0.3.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Upgrade to the latest version: pip install --upgrade pyequilib","cause":"The library version is too old (<0.2.0) or incorrectly installed.","error":"AttributeError: module 'equilib' has no attribute 'equi2pers'"},{"fix":"Install PyTorch: pip install torch, or use numpy-only functions: from equilib.numpy import equi2pers","cause":"Attempting to use PyTorch-specific functions when PyTorch is not installed.","error":"ModuleNotFoundError: No module named 'torch'"},{"fix":"Convert input to numpy array: np.array(your_list)","cause":"Functions expect numpy arrays or torch tensors, not lists.","error":"ValueError: Unknown input type: <class 'list'>"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}