addded documentation and examples

pygem/affine_trans.py

@@ -8,7 +8,7 @@
 
 def angles2matrix(rot_z=0, rot_y=0, rot_x=0):
 	"""
-	Returns matrix for given rotations around z, y and x axes. The output rotation matrix is
+	This method returns the rotation matrix for given rotations around z, y and x axes. The output rotation matrix is
 	equal to the composition of the	individual rotations. Rotations are counter-clockwise.
 	The default value of the three rotations is zero.
 
@@ -17,8 +17,19 @@ def angles2matrix(rot_z=0, rot_y=0, rot_x=0):
 	:param float rot_x: rotation angle (in radians) around x-axis.
 
 	:return: rot_matrix: rotation matrix for the given angles. The matrix shape is always (3, 3).
-	:rtype: float
+	:rtype: numpy.ndarray		  
+
+	:Example:
 
+	>>> import pygem.affine_trans as at
+	>>> import numpy as np
+
+	>>> # Example of a rotation around x, y, z axis 
+	>>> rotz = 10*np.pi/180
+	>>> roty = 20*np.pi/180
+	>>> rotx = 30*np.pi/180
+	>>> rot_matrix = at.angles2matrix(rotz, roty, rotx)
+
 	.. note::
 
 		- The direction of rotation is given by the right-hand rule.
@@ -54,9 +65,18 @@ def to_reduced_row_echelon_form(matrix):
 
 	:return matrix: the reduced matrix.
 	:rtype: matrix
+
+
+	:Example:
 
+	>>> import pygem.affine_trans as at
+
+	>>> matrix = [[1., 1., 1.], [1., 1., 1.], [1., 1., 1.]]
+	>>> rref_matrix = at.to_reduced_row_echelon_form(matrix)
+
 	.. note::
 		`matrix` will change after calling this function.
+
 	"""
 	lead = 0
 	row_count = len(matrix)
@@ -100,7 +120,7 @@ def affine_points_fit(points_start, points_end):
 
 	>>> import pygem.affine_trans as at
 
-	>>> # Example of a rotation
+	>>> # Example of a rotation (affine transformation)
 	>>> p_start = np.array([[1,0,0], [0,1,0], [0,0,1], [0,0,0]])
 	>>> p_end = np.array([[0,1,0], [-1,0,0], [0,0,1], [0,0,0]])
 	>>> v_test = np.array([1., 2., 3.])

pygem/ffd_parameters.py

@@ -47,11 +47,6 @@ class FFDParameters(object):
 	:cvar numpy.ndarray position_vertex_2: position of the third vertex of the FFD bounding box.
 	:cvar numpy.ndarray position_vertex_3: position of the fourth vertex of the FFD bounding box.
 
-	.. note::
-		Four vertex (non coplanar) are sufficient to uniquely identify a parallelepiped.
-		If the four vertex are coplanar, an assert is thrown when affine_points_fit is used.
-
-
 	:Example:
 
 	>>> import pygem.ffd_parameters as ffdp
@@ -64,6 +59,11 @@ class FFDParameters(object):
 	>>> # it is created with that name). So it is possible to manually edit it and read it again.
 	>>> params2 = ffdp.FFDParameters(n_control_points=[2, 3, 2])
 	>>> params2.read_parameters_file(filename='parameters_test.prm')
+
+	.. note::
+		Four vertex (non coplanar) are sufficient to uniquely identify a parallelepiped.
+		If the four vertex are coplanar, an assert is thrown when affine_points_fit is used.
+
     """
 
 	def __init__(self, n_control_points=None):
@@ -187,9 +187,8 @@ def write_parameters_file(self, filename='parameters.prm'):
 		"""
 		This method writes a parameters file (.prm) called `filename` and fills it with all
 		the parameters class members.
-
-		.. todo::
-			document better
+
+		:param string filename: paramters file to be written out.
 
 		"""
 		if not isinstance(filename, basestring):

pygem/free_form.py

@@ -12,9 +12,10 @@ class FFD(object):
 
 	:param class ffd_parameters: parameters of the Free Form Deformation.
 	:param numpy.ndarray original_mesh_points: coordinates of the original points of the mesh.
+
+	:cvar class parameters: parameters of the Free Form Deformation.
+	:cvar numpy.ndarray original_mesh_points: coordinates of the original points of the mesh.
 
-	:return: modified_mesh_points: coordinates of the modified points of the mesh.
-	:rtype: numpy.ndarray
     """
 
 	def __init__(self, ffd_parameters, original_mesh_points):
@@ -24,7 +25,26 @@ def __init__(self, ffd_parameters, original_mesh_points):
 
 	def perform(self):
 		"""
-		DOCS
+		This method performs the deformation on the mesh points.
+
+		:return: modified_mesh_points: coordinates of the modified points of the mesh.
+		:rtype: numpy.ndarray
+
+		:Example:
+
+		>>> import pygem.free_form as ffd
+		>>> import pygem.ffd_parameters as ffdp
+		>>> import numpy as np
+
+		>>> ffd_parameters = ffdp.FFDParameters()
+		>>> ffd_parameters.read_parameters_file(filename='tests/test_datasets/parameters_test_ffd_sphere.prm')
+		>>> original_mesh_points = np.load('tests/test_datasets/meshpoints_sphere_orig.npy')
+		>>> free_form = ffd.FFD(ffd_parameters, original_mesh_points)
+		>>> modified_mesh_points = free_form.perform()
+
+		.. todo::
+			In order to improve the performances, we need to perform the FFD only on the points inside the lattice.
+
 		"""
 		(n_rows_mesh, n_cols_mesh) = self.original_mesh_points.shape
 
@@ -91,7 +111,14 @@ def perform(self):
 
 	def _transform_points(self, original_points, transformation):
 		"""
-		DOCS
+		This method transforms the points according to the affine transformation taken from affine_points_fit method.
+
+		:param numpy.ndarray original_points: coordinates of the original points.
+		:param function transformation: affine transformation taken from affine_points_fit method.
+
+		:return: modified_points: coordinates of the modified points.
+		:rtype: numpy.ndarray
+
 		"""
 		n_rows_mesh, n_cols_mesh = original_points.shape
 		modified_points = np.zeros((n_rows_mesh, n_cols_mesh))

tests/test_ffd.py

@@ -3,7 +3,6 @@
 import unittest
 import pygem.free_form as ffd
 import pygem.ffd_parameters as ffdp
-import pygem.file_handler as fh
 import numpy as np