Commits

German Larrain committed 224c189

utils.mathematical: no code changes but lots of formatting; improved docstrings.

Comments (0)

Files changed (1)

ars/utils/mathematical.py

-
-# Created on 2011.08.09
-#
-# @author: german
-
-# TODO:	attribute the code sections that were taken from somewhere else
-
 """
 Functions to perform operations over vectors and matrices;
 deal with homogeneous transforms; convert angles and other structures.
 
 import generic as gut
 
-#===============================================================================
-# rotation directions are named by the third (z-axis) row of the 3x3 matrix, because ODE capsules
-# are oriented along the Z-axis
-#===============================================================================
+# TODO:	attribute the code sections that were taken from somewhere else
+
+#==============================================================================
+# rotation directions are named by the third (z-axis) row of the 3x3 matrix,
+# because ODE capsules are oriented along the Z-axis.
+#==============================================================================
 
 rightRot = (0.0, 0.0, -1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0)
 leftRot = (0.0, 0.0, 1.0, 0.0, 1.0, 0.0, -1.0, 0.0, 0.0)
 bkwdAxis = Z_AXIS  # direction: out of the screen
 fwdAxis = Z_AXIS_NEG  # direction: into the screen
 
-#===============================================================================
+#==============================================================================
 # added to the original refactored code
-#===============================================================================
+#==============================================================================
+
 
 def radians_to_degrees(radians_):
 	return degrees(radians_)
 
+
 # TODO: combine with the corresponding scalar-argument function
 def vec3_radians_to_degrees(vector_):
 	result = []
 		result.append(radians_to_degrees(radians_))
 	return tuple(result)
 
+
 def degrees_to_radians(degrees_):
 	return radians(degrees_)
 
+
 # TODO: combine with the corresponding scalar-argument function
 def vec3_degrees_to_radians(vector_):
 	result = []
 		result.append(degrees_to_radians(degrees_))
 	return tuple(result)
 
+
 def matrix3_multiply(matrix1, matrix2):
-	"""returns the matrix multiplication of matrix1 and matrix2"""
-	#TODO: check objects are valid, or use exceptions to catch errors raised by numpy
+	"""Return the matrix multiplication of ``matrix1`` and ``matrix2``."""
+	# TODO: check objects are valid, or use exceptions to catch errors raised
+	# by numpy
 
 	a1 = np.array(matrix1)
 	a2 = np.array(matrix2)
 
 	return matrix_as_3x3_tuples(tuple(result.flatten()))
 
+
 def matrix_as_tuple(matrix_):
-	"""\matrix_: nested tuples, e.g. ((1,0),(1,1),(2,5))"""
+	"""Convert ``matrix_`` to a tuple.
+
+	:param matrix_:
+	:type matrix_: nested tuples, e.g. ((1,0),(1,1),(2,5))
+
+	"""
 	#TODO: improve a lot
 	return gut.nested_iterable_to_tuple(matrix_)
 
+
 def matrix_as_3x3_tuples(tuple_9):
 	#TODO: improve a lot
 
 			matrix = (tuple_9[0:3], tuple_9[3:6], tuple_9[6:9])
 	return matrix
 
+
 def calc_acceleration(time_step, vel0, vel1):
-	"""Calculate the vectorial substraction `vel1` minus `vel0` divided by the
-	time step. If any of the vectors is `None`, then `None` is returned.
+	"""Calculate the vectorial substraction ``vel1 - vel0`` divided by
+	``time step``. If any of the vectors is ``None``, then ``None`` is returned.
 
-	`vel1` is the velocity measured `time_step` seconds after `vel0`.
+	``vel1`` is the velocity measured ``time_step`` seconds after ``vel0``.
 
 	"""
 	if vel0 is None or vel1 is None:
 
 
 def vector_matrix_vector(vector_, matrix_):
-	r"""Return the product of a transposed vector, a matrix and the same vector
-	again, which is a scalar value.
+	r"""Return the product of ``vector_`` transposed, ``matrix_`` and
+	``vector`` again, which is a scalar value.
 
 	.. math::
 		v^\top \mathbf{M} v
 	return np.dot(np.dot(np.array(vector_).T, np.array(matrix_)),
 		np.array(vector_))
 
-#===============================================================================
+#==============================================================================
 # Original code but formatted and some refactor
-#===============================================================================
+#==============================================================================
+
 
 def sign(x):
-	"""Returns 1.0 if x is positive, -1.0 if x is negative or zero"""
-	if x > 0.0: return 1.0
-	else: return -1.0
+	"""Return ``1.0`` if ``x`` is positive, ``-1.0`` otherwise."""
+	if x > 0.0:
+		return 1.0
+	else:
+		return -1.0
+
 
 def length2(vector):
-	"""Returns the length of a 2-dimensions vector"""
-	return sqrt(vector[0]**2 + vector[1]**2)
+	"""Return the length of a 2-dimension ``vector``."""
+	return sqrt(vector[0] ** 2 + vector[1] ** 2)
+
 
 def length3(vector):
-	"""Returns the length of a 3-dimensions vector"""
+	"""Return the length of a 3-dimension ``vector``."""
 	#TODO: convert it so it can handle vector of any dimension
-	return sqrt(vector[0]**2 + vector[1]**2 + vector[2]**2)
+	return sqrt(vector[0] ** 2 + vector[1] ** 2 + vector[2] ** 2)
+
 
 def neg3(vector):
-	"""Returns the negation of 3-vector vector"""
+	"""Return the negation of 3-dimension ``vector``."""
 	#TODO: convert it so it can handle vector of any dimension
 	return (-vector[0], -vector[1], -vector[2])
 
+
 def add3(vector1, vector2):
-	"""Returns the sum of 3-vectors vector1 and vector2"""
+	"""Return the sum of 3-dimension ``vector1`` and ``vector2``."""
 	#TODO: convert it so it can handle vector of any dimension
-	return (vector1[0] + vector2[0], vector1[1] + vector2[1], vector1[2] + vector2[2])
+	return (vector1[0] + vector2[0],
+			vector1[1] + vector2[1],
+			vector1[2] + vector2[2])
+
 
 def sub3(vector1, vector2):
-	"""Returns the difference between 3-vectors vector1 and vector2"""
+	"""Return the difference between 3-dimension ``vector1`` and ``vector2``."""
 	#TODO: convert it so it can handle vector of any dimension
-	return (vector1[0] - vector2[0], vector1[1] - vector2[1], vector1[2] - vector2[2])
+	return (vector1[0] - vector2[0],
+			vector1[1] - vector2[1],
+			vector1[2] - vector2[2])
+
 
 def mult_by_scalar3(vector, scalar):
-	"""Returns 3-vector vector multiplied by scalar scalar"""
+	"""Return 3-dimension ``vector`` multiplied by ``scalar``."""
 	#TODO: convert it so it can handle vector of any dimension
 	return (vector[0] * scalar, vector[1] * scalar, vector[2] * scalar)
 
+
 def div_by_scalar3(vector, scalar):
-	"""Returns 3-vector vector divided by scalar scalar"""
+	"""Return 3-dimension ``vector`` divided by ``scalar``."""
 	#TODO: convert it so it can handle vector of any dimension
 	return (vector[0] / scalar, vector[1] / scalar, vector[2] / scalar)
 
+
 def dist3(vector1, vector2):
-	"""Returns the distance between point 3-vectors vector1 and vector2"""
+	"""Return the distance between point 3-dimension ``vector1`` and
+	``vector2``.
+
+	"""
 	#TODO: convert it so it can handle vector of any dimension
 	return length3(sub3(vector1, vector2))
 
+
 def norm3(vector):
-	"""Returns the unit length 3-vector parallel to 3-vector vector"""
+	"""Return the unit length vector parallel to 3-dimension ``vector``."""
 	#l = length3(vector)
 	#if l > 0.0:
 	#	return (vector[0] / l, vector[1] / l, vector[2] / l)
 	#	return (0.0, 0.0, 0.0)
 	return unitize(vector)
 
+
 def unitize(vector_):
-	"""Unitize a vector, i.e. return a unit-length vector parallel to `vector`
+	"""Unitize a vector, i.e. return a unit-length vector parallel to
+	``vector``.
 
 	"""
 	len_ = sqrt(sum(itertools.imap(operator.mul, vector_, vector_)))
 	else:
 		return (0.0, 0.0, 0.0)
 
+
 def dot_product3(vector1, vector2):
-	"""Returns the dot product of 3-vectors vector1 and vector2"""
+	"""Return the dot product of 3-dimension ``vector1`` and ``vector2``."""
 	return dot_product(vector1, vector2)
 
+
 def dot_product(vec1, vec2):
 	"""Efficient dot-product operation between two vectors of the same size.
 	source: http://docs.python.org/library/itertools.html
 	"""
 	return sum(itertools.imap(operator.mul, vec1, vec2))
 
+
 def cross_product(vector1, vector2):
-	"""Returns the cross_product product of length-3 vectors `vector1` and
-	`vector2`
-
-	"""
+	"""Return the cross product of 3-dimension ``vector1`` and ``vector2``."""
 	return (vector1[1] * vector2[2] - vector1[2] * vector2[1],
 		vector1[2] * vector2[0] - vector1[0] * vector2[2],
 		vector1[0] * vector2[1] - vector1[1] * vector2[0])
 
+
 def project3(vector, unit_vector):
-	"""Returns projection of 3-vector vector onto unit 3-vector unit_vector"""
+	"""Return projection of 3-dimension ``vector`` onto unit 3-dimension
+	``unit_vector``.
+
+	"""
 	#TODO: convert it so it can handle vector of any dimension
 	return mult_by_scalar3(vector, dot_product3(norm3(vector), unit_vector))
 
+
 def acos_dot3(vector1, vector2):
-	"""Returns the angle between unit 3-vectors vector1 and vector2"""
+	"""Return the angle between unit 3-dimension ``vector1`` and ``vector2``."""
 	x = dot_product3(vector1, vector2)
-	if x < -1.0: return pi
-	elif x > 1.0: return 0.0
-	else: return acos(x)
+	if x < -1.0:
+		return pi
+	elif x > 1.0:
+		return 0.0
+	else:
+		return acos(x)
+
 
 def rotate3(rot_matrix, vector):
-	"""Returns the rotation of 3-vector vector by 3x3 (row major) matrix rot_matrix"""
-	return (vector[0] * rot_matrix[0] + vector[1] * rot_matrix[1] + vector[2] * rot_matrix[2],
-		vector[0] * rot_matrix[3] + vector[1] * rot_matrix[4] + vector[2] * rot_matrix[5],
-		vector[0] * rot_matrix[6] + vector[1] * rot_matrix[7] + vector[2] * rot_matrix[8])
+	"""Return the rotation of 3-dimension ``vector`` by 3x3 (row major) matrix
+	``rot_matrix``.
+
+	"""
+	return (vector[0] * rot_matrix[0] + vector[1] * rot_matrix[1] +
+			vector[2] * rot_matrix[2],
+			vector[0] * rot_matrix[3] + vector[1] * rot_matrix[4] +
+			vector[2] * rot_matrix[5],
+			vector[0] * rot_matrix[6] + vector[1] * rot_matrix[7] +
+			vector[2] * rot_matrix[8])
+
 
 def transpose3(matrix):
-	"""Returns the inversion (transpose) of 3x3 rotation matrix matrix"""
+	"""Return the inversion (transpose) of 3x3 rotation matrix ``matrix``."""
 	#TODO: convert it so it can handle vector of any dimension
 	return (matrix[0], matrix[3], matrix[6],
 		matrix[1], matrix[4], matrix[7],
 		matrix[2], matrix[5], matrix[8])
 
+
 def z_axis(rot_matrix):
-	"""Returns the z-axis vector from 3x3 (row major) rotation matrix rot_matrix"""
+	"""Return the z-axis vector from 3x3 (row major) rotation matrix
+	``rot_matrix``.
+
+	"""
 	#TODO: convert it so it can handle vector of any dimension, and any column
 	return (rot_matrix[2], rot_matrix[5], rot_matrix[8])
 
-#===============================================================================
+#==============================================================================
 # TESTS
-#===============================================================================
+#==============================================================================
+
 
 def _test_angular_conversions(angle_):
 	#x = 2.0/3*pi
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.