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
- 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).
- Fix the coordinate convention at the source so it matches
equi2equi/equi2pers, and remove z_down = not z_down from both backends.
- 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
Summary
equi2cubeflips the user'sz_downargument 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
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
equi2cubebuilds 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/equi2persconvert_grid:uj = (phi + π/2)·h/π→ row 0 = -phi (down)So
equi2cube'sxyz/grid construction uses an inverted z relative to the rest of the library, and thez_down = not z_downflip compensates for that mismatch. The proper fix is to makeequi2cube's coordinate convention consistent with the other transforms (likely increate_xyz_gridor theconvert_gridlatitude term) and then delete the flip.A related
# FIXME: needs to test thissits 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/rollcomposition on the up/down faces, allcube_formats).Proposed work
z_down,roll/pitch/yaw, and everycube_format).equi2equi/equi2pers, and removez_down = not z_downfrom both backends.equi2cubeorientation (and resolve theneeds to test thisFIXME).Milestone
Deferred from 0.6.0 (pre-existing behavior, not a regression). Target: 0.6.1.
🤖 Filed with Claude Code