Inclination vs elevation

[Lestropie]

I've been aware of this one for a while, but didn't realise that I had not listed it. Has come back to the front of my mind due to playing with particularly #2626.

Spherical coordinates can be defined using different conventions, in terms or presence or absence of elements / ordering of elements / symbols for elements / reference & range for quantities. In BIDS BEP016 I've stuck to ISO standard as much as possible. In MRtrix3 code, one frequently sees references in this context to "az_el", ie. azimuth-elevation pairs. However the cos / acos transformations indicate that the origin of the second spherical angle is the z-axis. This would make it an inclination rather than elevation angle: the former uses the angle from the zenith direction, the latter uses the angle from the reference plane.

• [ ] Do code audit to make sure that there are no fundamental conflicts in how such values are transformed / interpreted in various places. One potential culprit I'm thinking of here is the calculation of lighting effects in OpenGL code.
• [ ] Find any manual manipulation of spherical vs cartesian directions and centralise it all to MR::Math::Sphere. I've already done this a little in #2626 and related, but it needs a more exhaustive search.
• [ ] Rename variables to properly reflect the actual encoding.
• [ ] Add somewhere in documentation the way in which such data are imported / exported. This could potentially include a copy-paste help page Description paragraph, or a version-matched documentation hyperlink.

[fionaEyoung]

Here's a summary of some of the different conventions I've dealt with across different tools over the years. Not particularly helpful for the tasks listed above, but it's good to know what users may or may not be assuming when mixing tools/packages...

Source	XY plane	Z axis	Order
Scipy sph_harm	𝜽 "azimuth" [0,2π]	𝝓 "polar" [0,π]	[az, pol]
Dipy sphere2cart / cart2sphere	𝝓 "azimuth" [-π,π]	𝜽 "incl/polar" [0,π]	[r, pol, az]
Descoteaux 2006	𝝓 [0,2π]	𝜽 [0,π]
matlab cart2sph	"azimuth" [-π,π]	"elevation" [-π/2, π/2]	[az, el, r]
CSD matlab s2c	"azimuth" [-π,π]	"elevation" [0,π]	[el, az, r]

[Lestropie]

True; might we worth expanding the scope of the issue to cover the order of coefficients. The expected ranges should ideally not be of consequence since they should wash out in any relevant calculations; what matters most is the definition of where zero is. For inclination vs elevation as polar angle in particular, there should be a bunch of cos() / acos() vs. sin() / asin() calls in conversions to / from Cartesian.

The inhomogeneity certainly justifies my assertion of enforcing ISO in BEP016... 😄

[fionaEyoung]

The expected ranges should ideally not be of consequence since they should wash out in any relevant calculations

Indeed, and I was thinking that some functions may enforce the ranges through input checks, but for example even though the scipy sph_harm documentation says "must be in [0, 2*pi]", it looks like that isn't actually inforced and it accepts negative values just fine...