# Commits

committed ab0ca24

utils: fixed and improved docstrings

# ars/utils/geometry.py


 	Translated to Python by German Larrain.

-	Original version in Matlab, part of	'The Robotics Toolbox for Matlab (RTB)'
+	Original version in Matlab, part of 'The Robotics Toolbox for Matlab (RTB)'
 	as '/robot/tr2rpy.m'
 	Copyright (C) 1993-2011, by Peter I. Corke. See rtb_license.


 class Transform:

-	"""An homogeneous transform."""
+	r"""An homogeneous transform.
+
+	It is a composition of rotation and translation. Mathematically it can be
+	expressed as
+
+	.. math::
+
+		\left[
+		\begin{array}{ccc|c}
+			 &  &  &  \\
+			 & R &  & T \\
+			 & &  &  \\
+			\hline
+			0 & 0 & 0 & 1
+		  \end{array}
+		\right]
+
+	where R is the 3x3 submatrix describing rotation and T is the
+	3x1 submatrix describing translation.
+
+	source:
+	http://en.wikipedia.org/wiki/Denavit%E2%80%93Hartenberg_parameters#Denavit-Hartenberg_matrix
+
+	"""

 	def __init__(self, position, rot_matrix):
 		"""Constructor.
 def rot_matrix_to_hom_transform(rot_matrix):
 	"""Convert a rotation matrix to a homogeneous transform.

-	From transform.r2t in Corke's Robotic Toolbox (python) rot_matrix 3x3
-	matrix.
+	source: transform.r2t in Corke's Robotic Toolbox (python)

-	:param rot_matrix: a tuple, a tuple of tuples or the result of
-		numpy.mat()
+	:param rot_matrix: 3x3 matrix
+	:type rot_matrix: a tuple, a tuple of tuples or :class:numpy.mat

 	"""
-
 	if isinstance(rot_matrix, tuple):
 		if len(rot_matrix) == 9:
 			rot_matrix = (rot_matrix[0:3], rot_matrix[3:6], rot_matrix[6:9])
 	matrix rot_matrix, with respect to the plane (XZ, since the vertical
 	axis is Y). pitch is the rotation around Z and roll around Y.

-	Examples::
+	Examples:

-		rot_matrix = calc_rotation_matrix((1.0, 0.0, 0.0), pi/6)
-		pitch, roll = gemut.calc_inclination(rot_matrix)
-		pitch: 0.0, roll: pi/6
+	>>> rot_matrix = calc_rotation_matrix((1.0, 0.0, 0.0), pi/6)
+	>>> pitch, roll = gemut.calc_inclination(rot_matrix)
+	0.0, pi/6

-		rot_matrix = calc_rotation_matrix((0.0, 1.0, 0.0), whatever)
-		pitch, roll = gemut.calc_inclination(rot_matrix)
-		pitch: 0.0, roll: 0.0
+	>>> rot_matrix = calc_rotation_matrix((0.0, 1.0, 0.0), whatever)
+	>>> pitch, roll = gemut.calc_inclination(rot_matrix)
+	0.0, 0.0

-		rot_matrix = calc_rotation_matrix((0.0, 0.0, 1.0), pi/6)
-		pitch, roll = gemut.calc_inclination(rot_matrix)
-		pitch: pi/6, roll: 0.0
+	>>> rot_matrix = calc_rotation_matrix((0.0, 0.0, 1.0), pi/6)
+	>>> pitch, roll = gemut.calc_inclination(rot_matrix)
+	pi/6, 0.0

 	"""
 	# THE FOLLOWING worked only in some cases, damn

# ars/utils/mathematical.py



 def matrix_as_3x3_tuples(tuple_9):
-	#TODO: improve a lot
+	"""Return tuple_9 as a 3-tuple of 3-tuples.
+
+	:param tuple_9: tuple of 9 elements
+	:return: tuple_9 formatted as tuple of tuples
+
+	"""
+	#TODO: convert it to handle square matrices of any size

 	matrix = None
 	if isinstance(tuple_9, tuple):