Commits

German Larrain committed ab0ca24

utils: fixed and improved docstrings

Comments (0)

Files changed (2)

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):