Equirectangle Images

Panorama v.s. Equirectangular Image

Equirectangular/Lat-Long Image is a specific projection commonly used to store a full spherical 360°×180° panorama, where longitude maps linearly to the x-axis and latitude maps linearly to the y-axis (typically yielding a 2:1 aspect ratio).

Panorama is a broad term for any image that captures a wider-than-normal field of view. Usually a 360° spherical panorama is stored as an equirectangular image, but not all panoramas are equirectangular! (e.g., your photo may be able to take partial cylindrical panorama, which is not an equirectangular image.)

Environment maps are also typically stored as equirectangular images for 360° lighting, but they can also be saved in other projections like a cubemap. They are usually HDR images, stored in .hdr or .exr format to preserve float32 precision.

Equirect Projection

We can project equirect images into normal images with arbitrary camera intrinsics, which is useful for curating camera datasets.

API

kiui.equirect.tonemap_hdr_to_ldr(image: ndarray, percentile: float = 90.0, max_mapping: float = 0.8, gamma: float = 2.0, clip: bool = True) → ndarray[source]

Tonemap an HDR image to an LDR image.

Parameters:

  • image – HDR image, [0, inf], float32

  • percentile – use this percentile of brightness for exposure normalization, ignoring extreme highlights (e.g., sun, specular reflections).

  • max_mapping – target brightness after normalization, <1.0 leaves headroom for soft clipping instead of harsh cutoff.

  • gamma – gamma correction exponent, compensates for human perception being logarithmic (boosts darks, compresses brights).

  • clip – clip the image to [0, 1]

Returns:

LDR image, [0, 1], float32

kiui.equirect.render_pinhole(pano: Tensor, height: int, width: int, vfov: Tensor, roll: Tensor, pitch: Tensor, yaw: Tensor) → Tensor[source]

Render pinhole images from a panorama given the camera parameters. We use CUDA and F.grid_sample for efficient rendering.

Parameters:

  • pano – [3, Hp, Wp], float tensor, panorama image.

  • height – int, image height

  • width – int, image width

  • vfov – [B,], float tensor, vertical field of view in radians

  • roll – [B,], float tensor, roll angle in radians

  • pitch – [B,], float tensor, pitch angle in radians

  • yaw – [B,], float tensor, yaw angle in radians

Returns:

[B, 3, H, W], float tensor, pinhole images rendered from the panorama.

Return type:

images