From 76de9ba259313e21831678d986bca0af05559bd4 Mon Sep 17 00:00:00 2001
From: Alexander Fabisch <alexander.fabisch@dfki.de>
Date: Thu, 28 Sep 2023 11:17:16 +0200
Subject: [PATCH] Explain orthonormalization

---
 doc/source/rotations.rst          |  2 +-
 pytransform3d/rotations/_utils.py | 37 ++++++++++++++++++++++++++++---
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/doc/source/rotations.rst b/doc/source/rotations.rst
index c1c7aba57..d418c6d0c 100644
--- a/doc/source/rotations.rst
+++ b/doc/source/rotations.rst
@@ -90,7 +90,7 @@ A more compact representation of these constraints is
 \Leftrightarrow \boldsymbol R^T = \boldsymbol R^{-1}`.
 
 In addition, :math:`\det(\boldsymbol R) = 1` because we use right-handed
-coordinate system   (:math:`\det(\boldsymbol R) = -1` for left-handed
+coordinate system (:math:`\det(\boldsymbol R) = -1` for left-handed
 coordinate systems).
 
 Hence, the group :math:`SO(3)` is defined as
diff --git a/pytransform3d/rotations/_utils.py b/pytransform3d/rotations/_utils.py
index 3740c08e1..9d37224fd 100644
--- a/pytransform3d/rotations/_utils.py
+++ b/pytransform3d/rotations/_utils.py
@@ -26,17 +26,44 @@ def norm_vector(v):
 
 
 def norm_matrix(R):
-    """Orthonormalize rotation matrix.
+    r"""Orthonormalize rotation matrix.
+
+    A rotation matrix is defined as
+
+    .. math::
+
+        \boldsymbol R =
+        \left( \begin{array}{ccc}
+            r_{11} & r_{12} & r_{13}\\
+            r_{21} & r_{22} & r_{23}\\
+            r_{31} & r_{32} & r_{33}\\
+        \end{array} \right)
+        \in SO(3)
+
+    and must be orthonormal, which results in 6 constraints:
+
+    * column vectors must have unit norm (3 constraints)
+    * and must be orthogonal to each other (3 constraints)
+
+    A more compact representation of these constraints is
+    :math:`\boldsymbol R^T \boldsymbol R = \boldsymbol I`.
+
+    Because of numerical problems, a rotation matrix might not satisfy the
+    constraints anymore. This function will enforce them.
 
     Parameters
     ----------
     R : array-like, shape (3, 3)
-        Rotation matrix with small numerical errors
+        Rotation matrix with small numerical errors.
 
     Returns
     -------
     R : array, shape (3, 3)
-        Normalized rotation matrix
+        Orthonormalized rotation matrix.
+
+    See Also
+    --------
+    check_matrix : Checks orthonormality of a rotation matrix.
     """
     R = np.asarray(R)
     c2 = R[:, 1]
@@ -431,6 +458,10 @@ def check_matrix(R, tolerance=1e-6, strict_check=True):
     ------
     ValueError
         If input is invalid
+
+    See Also
+    --------
+    norm_matrix : Enforces orthonormality of a rotation matrix.
     """
     R = np.asarray(R, dtype=np.float64)
     if R.ndim != 2 or R.shape[0] != 3 or R.shape[1] != 3: