# Spherical coordinates¶

Orientation-related commands (e.g. cylinderorientation) use spherical coordinates defined in the figure below. Namely, $$\phi$$ refers to the azimuthal angle and $$\theta$$ to the polar angle. The azimuthal angle is measured in $$xy$$-plane from the positive $$x$$-axis towards the positive $$y$$-axis, and its values are always in the range $$[-\pi, \pi]$$. The polar angle is measured from the positive $$z$$-axis towards the $$xy$$-plane, and its values are always in the range $$[0, \pi]$$.

Conversion from the cartesian coordinates to the polar coordinates is done with

$\begin{split}r &= \sqrt{x^2 + y^2 + z^2} \\ \phi &= \operatorname{arctan2}(y, x) \\ \theta &= \arccos(z / r)\end{split}$

Conversion from the polar coordinates to the cartesian coordinates is done with

$\begin{split}x &= r \cos(\phi) sin(\theta) \\ y &= r \sin(\phi) sin(\theta) \\ z &= r \cos(\theta)\end{split}$

Most orientation-related commands return only angles for which the cartesian $$x$$-component is positive. This is because the orientations are symmetrical, i.e. directions $$-\vec{r}$$ and $$\vec{r}$$ describe the same orientation, and therefore half of the possible directions are redundant. Additionally, in orientation-related commands $$r=1$$ most of the time.