Skip to content

equi2cube z-axis orientation: remove the z_down = not z_down hack #38

Description

@haruishi43

Summary

equi2cube flips the user's z_down argument internally before building the rotation matrices, with a FIXME admitting the reason is unknown:

https://github.com/haruishi43/equilib/blob/master/equilib/equi2cube/numpy.py#L174-L177

# FIXME: not sure why, but z-axis is facing the opposite
# probably I need to change the way I choose the xyz coordinates
# this is a temporary fix for now
z_down = not z_down

The same hack exists in the torch backend (equilib/equi2cube/torch.py, ~L206-L209). It's a band-aid for an un-diagnosed orientation inconsistency, not a real fix.

Likely root cause

equi2cube builds its grid with the opposite latitude convention to the other equi-sampling transforms:

  • equi2cube/convert_grid: uj = (0.5 - phi/π)·h - 0.5 → row 0 = +phi (up)
  • equi2equi / equi2pers convert_grid: uj = (phi + π/2)·h/π → row 0 = -phi (down)

So equi2cube's xyz/grid construction uses an inverted z relative to the rest of the library, and the z_down = not z_down flip compensates for that mismatch. The proper fix is to make equi2cube's coordinate convention consistent with the other transforms (likely in create_xyz_grid or the convert_grid latitude term) and then delete the flip.

A related # FIXME: needs to test this sits near the output assembly (equilib/equi2cube/numpy.py ~L203), indicating untested paths in the same transform.

Why it matters

This is the one place in a core transform where the behavior is "works but not sure why." Current tests mostly check numpy/torch parity and shapes, not geometric ground truth, so the orientation could be only coincidentally correct for the tested cases (e.g. z_down=True, pitch/roll composition on the up/down faces, all cube_formats).

Proposed work

  1. Reproduce with a synthetic equirectangular image whose regions map to distinct, identifiable cube faces; verify each face lands in the geometrically correct place (and across z_down, roll/pitch/yaw, and every cube_format).
  2. Fix the coordinate convention at the source so it matches equi2equi/equi2pers, and remove z_down = not z_down from both backends.
  3. Add a geometric ground-truth regression test for equi2cube orientation (and resolve the needs to test this FIXME).

Milestone

Deferred from 0.6.0 (pre-existing behavior, not a regression). Target: 0.6.1.

🤖 Filed with Claude Code

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions