Added documentation to functions for coordinate transforms

sfs/util.py

@@ -57,7 +57,34 @@ def direction_vector(alpha, beta=np.pi/2):
 
 
 def sph2cart(alpha, beta, r):
-    """Spherical to cartesian coordinates."""
+    r"""Spherical to cartesian coordinate transform.
+
+    .. math::
+
+        x = r \cos \alpha \sin \beta \\
+        y = r \sin \alpha \sin \beta \\
+        z = r \cos \beta
+
+    with :math:`\alpha \in [0, 2\pi), \beta \in [0, \pi], r \geq 0`
+
+    Parameters
+    ----------
+    alpha : float or array_like
+            Azimuth angle in radiants
+    beta : float or array_like
+            Elevation angle in radiants (with 0 denoting North pole)
+    r : float or array_like
+            Radius
+
+    Returns
+    -------
+    x : float or array_like
+        x-component of Cartesian coordinates
+    y : float or array_like
+        y-component of Cartesian coordinates
+    z : float or array_like
+        z-component of Cartesian coordinates
+    """
     x = r * np.cos(alpha) * np.sin(beta)
     y = r * np.sin(alpha) * np.sin(beta)
     z = r * np.cos(beta)
@@ -66,7 +93,34 @@ def sph2cart(alpha, beta, r):
 
 
 def cart2sph(x, y, z):
-    """Cartesian to spherical coordinates."""
+    r"""Cartesian to spherical coordinate transform.
+
+    .. math::
+
+        \alpha = \arctan \left( \frac{y}{x} \right) \\
+        \beta = \arccos \left( \frac{z}{r} \right) \\
+        r = \sqrt{x^2 + y^2 + z^2}
+
+    with :math:`\alpha \in [0, 2\pi), \beta \in [0, \pi], r \geq 0`
+
+    Parameters
+    ----------
+    x : float or array_like
+        x-component of Cartesian coordinates
+    y : float or array_like
+        y-component of Cartesian coordinates
+    z : float or array_like
+        z-component of Cartesian coordinates
+
+    Returns
+    -------
+    alpha : float or array_like
+            Azimuth angle in radiants
+    beta : float or array_like
+            Elevation angle in radiants (with 0 denoting North pole)
+    r : float or array_like
+            Radius
+    """
     r = np.sqrt(x**2 + y**2 + z**2)
     alpha = np.arctan2(y, x)
     beta = np.arccos(z / r)