From a9ebb690d1b15d14f5ba8d6245c5f58f6f490743 Mon Sep 17 00:00:00 2001 From: fsalmoir Date: Thu, 24 Mar 2016 17:49:06 +0100 Subject: [PATCH] addded documentation and examples --- pygem/affine_trans.py | 26 +++++++++++++++++++++++--- pygem/ffd_parameters.py | 15 +++++++-------- pygem/free_form.py | 35 +++++++++++++++++++++++++++++++---- tests/test_ffd.py | 1 - 4 files changed, 61 insertions(+), 16 deletions(-) diff --git a/pygem/affine_trans.py b/pygem/affine_trans.py index 2574a64..772f150 100644 --- a/pygem/affine_trans.py +++ b/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.]) diff --git a/pygem/ffd_parameters.py b/pygem/ffd_parameters.py index fc07801..c3b26d2 100644 --- a/pygem/ffd_parameters.py +++ b/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): diff --git a/pygem/free_form.py b/pygem/free_form.py index 1780673..df8883d 100644 --- a/pygem/free_form.py +++ b/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)) diff --git a/tests/test_ffd.py b/tests/test_ffd.py index 408494c..047b63d 100644 --- a/tests/test_ffd.py +++ b/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