Merge pull request #4 from M-SenseResearchGroup/development

Sphinx documentation
M-SenseResearchGroup · Oct 19, 2019 · bf8591e · bf8591e
2 parents d59fd42 + 08b05e9
commit bf8591e
Show file tree

Hide file tree

Showing 32 changed files with 216 additions and 31 deletions.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -34,7 +34,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'numpydoc', 'sphinx_rtd_theme']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.autosummary', 'numpydoc', 'sphinx_rtd_theme']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -45,6 +45,8 @@
 exclude_patterns = []
 
 autoclass_content = 'both'
+autosummary_generate = True
+# autosummary_imported_members = True
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:

diff --git a/docs/source/ref/core.rst b/docs/source/ref/core.rst
@@ -1,11 +1,10 @@
 .. pykinematics API reference: core
 .. currentmodule:: pykinematics
 
-API Reference
+pykinematics
 =============
 
-.. autoclass:: MimuAngles
-  :members: calibrate, estimate
+.. toctree::
 
-.. autoclass:: OmcAngles
-  :members:
+  core/MimuAngles
+  core/OmcAngles
diff --git a/docs/source/ref/core/MimuAngles.rst b/docs/source/ref/core/MimuAngles.rst
@@ -0,0 +1,7 @@
+pykinematics.MimuAngles
+=======================
+
+.. currentmodule:: pykinematics
+
+.. autoclass:: MimuAngles
+  :members: calibrate, estimate
diff --git a/docs/source/ref/core/OmcAngles.rst b/docs/source/ref/core/OmcAngles.rst
@@ -0,0 +1,24 @@
+pykinematics.OmcAngles
+======================
+
+.. currentmodule:: pykinematics
+
+.. autoclass:: OmcAngles
+
+
+   .. automethod:: __init__
+
+
+   .. rubric:: Methods
+
+   .. autosummary::
+
+      ~OmcAngles.__init__
+      ~OmcAngles.calibrate
+      ~OmcAngles.estimate
+
+
+
+
+
+
diff --git a/docs/source/ref/imu.rst b/docs/source/ref/imu.rst
@@ -0,0 +1,13 @@
+.. pykinematics API reference: imu
+.. currentmodule:: pykinematics
+
+pykinematics.imu
+=============
+
+.. toctree::
+
+  imu/calibration
+  imu/joints
+  imu/orientation
+  imu/angles
+  imu/utility
diff --git a/docs/source/ref/imu/angles.hip_from_frames.rst b/docs/source/ref/imu/angles.hip_from_frames.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.angles.hip_from_frames
+=======================================
+
+.. currentmodule:: pykinematics.imu.angles
+
+.. autofunction:: hip_from_frames
diff --git a/docs/source/ref/imu/angles.rst b/docs/source/ref/imu/angles.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.angles
+=======================
+
+.. toctree::
+
+  angles.hip_from_frames
diff --git a/docs/source/ref/imu/calibration.rst b/docs/source/ref/imu/calibration.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.calibration
+===================================
+
+.. toctree::
+
+  calibration.static
diff --git a/docs/source/ref/imu/calibration.static.rst b/docs/source/ref/imu/calibration.static.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.calibration.static
+===================================
+
+.. currentmodule:: pykinematics.imu.calibration
+
+.. autofunction:: static
diff --git a/docs/source/ref/imu/joints.Center.rst b/docs/source/ref/imu/joints.Center.rst
@@ -0,0 +1,7 @@
+pykinematics.imu.joints.Center
+==============================
+
+.. currentmodule:: pykinematics.imu.joints
+
+.. autoclass:: Center
+  :members: compute
diff --git a/docs/source/ref/imu/joints.KneeAxis.rst b/docs/source/ref/imu/joints.KneeAxis.rst
@@ -0,0 +1,7 @@
+pykinematics.imu.joints.KneeAxis
+================================
+
+.. currentmodule:: pykinematics.imu.joints
+
+.. autoclass:: KneeAxis
+  :members: compute
diff --git a/docs/source/ref/imu/joints.correct_knee.rst b/docs/source/ref/imu/joints.correct_knee.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.joints.correct_knee
+====================================
+
+.. currentmodule:: pykinematics.imu.joints
+
+.. autofunction:: correct_knee
diff --git a/docs/source/ref/imu/joints.fixed_axis.rst b/docs/source/ref/imu/joints.fixed_axis.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.joints.fixed_axis
+==================================
+
+.. currentmodule:: pykinematics.imu.joints
+
+.. autofunction:: fixed_axis
diff --git a/docs/source/ref/imu/joints.rst b/docs/source/ref/imu/joints.rst
@@ -0,0 +1,9 @@
+pykinematics.imu.joints
+=======================
+
+.. toctree::
+
+  joints.Center
+  joints.correct_knee
+  joints.KneeAxis
+  joints.fixed_axis
diff --git a/docs/source/ref/imu/orientation.MadgwickAHRS.rst b/docs/source/ref/imu/orientation.MadgwickAHRS.rst
@@ -0,0 +1,7 @@
+pykinematics.imu.orientation.MadgwickAHRS
+=========================================
+
+.. currentmodule:: pykinematics.imu.orientation
+
+.. autoclass:: MadgwickAHRS
+  :members: update, updateIMU
diff --git a/docs/source/ref/imu/orientation.OrientationComplementaryFilter.rst b/docs/source/ref/imu/orientation.OrientationComplementaryFilter.rst
@@ -0,0 +1,7 @@
+pykinematics.imu.orientation.OrientationComplementaryFilter
+===========================================================
+
+.. currentmodule:: pykinematics.imu.orientation
+
+.. autoclass:: OrientationComplementaryFilter
+  :members: run
diff --git a/docs/source/ref/imu/orientation.SSRO.rst b/docs/source/ref/imu/orientation.SSRO.rst
@@ -0,0 +1,7 @@
+pykinematics.imu.orientation.SSRO
+=================================
+
+.. currentmodule:: pykinematics.imu.orientation
+
+.. autoclass:: SSRO
+  :members: run
diff --git a/docs/source/ref/imu/orientation.rst b/docs/source/ref/imu/orientation.rst
@@ -0,0 +1,8 @@
+pykinematics.imu.orientation
+============================
+
+.. toctree::
+
+  orientation.MadgwickAHRS
+  orientation.OrientationComplementaryFilter
+  orientation.SSRO
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.calc_derivative.rst b/docs/source/ref/imu/pykinematics.imu.utility.calc_derivative.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.calc\_derivative
+=========================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: calc_derivative
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.quat2matrix.rst b/docs/source/ref/imu/pykinematics.imu.utility.quat2matrix.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.quat2matrix
+====================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: quat2matrix
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.quat_conj.rst b/docs/source/ref/imu/pykinematics.imu.utility.quat_conj.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.quat\_conj
+===================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: quat_conj
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.quat_inv.rst b/docs/source/ref/imu/pykinematics.imu.utility.quat_inv.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.quat\_inv
+==================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: quat_inv
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.quat_mean.rst b/docs/source/ref/imu/pykinematics.imu.utility.quat_mean.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.quat\_mean
+===================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: quat_mean
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.quat_mult.rst b/docs/source/ref/imu/pykinematics.imu.utility.quat_mult.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.quat\_mult
+===================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: quat_mult
diff --git a/docs/source/ref/imu/pykinematics.imu.utility.vec2quat.rst b/docs/source/ref/imu/pykinematics.imu.utility.vec2quat.rst
@@ -0,0 +1,6 @@
+pykinematics.imu.utility.vec2quat
+=================================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autofunction:: vec2quat
diff --git a/docs/source/ref/imu/utility.rst b/docs/source/ref/imu/utility.rst
@@ -0,0 +1,15 @@
+pykinematics.imu.utility
+=======================
+
+.. currentmodule:: pykinematics.imu.utility
+
+.. autosummary::
+  :toctree:
+
+  calc_derivative
+  quat_mult
+  quat_conj
+  quat_inv
+  quat_mean
+  vec2quat
+  quat2matrix
diff --git a/docs/source/ref/index.rst b/docs/source/ref/index.rst
@@ -3,7 +3,10 @@
 API Reference
 =============
 
+.. currentmodule:: pykinematics
+
 .. toctree::
   :maxdepth: 3
 
   core
+  imu
diff --git a/pykinematics/imu/lib/angles.py b/pykinematics/imu/lib/angles.py
@@ -16,7 +16,7 @@
 
 def hip_from_frames(pelvis_AF, thigh_AF, R, side, zero_angles=False):
     """
-    Compute the hip joint angles from fixed and reference axes from the anatomical frames.
+    Compute the hip joint angles from the segment fixed axes computed during the calibration.
 
     Parameters
     ----------

diff --git a/pykinematics/imu/lib/joints.py b/pykinematics/imu/lib/joints.py
@@ -17,7 +17,7 @@
 class Center:
     def __init__(self, g=9.81, method='SAC', mask_input=True, min_samples=1000, mask_data='acc', opt_kwargs=None):
         """
-        Object for joint center computation
+        Estimation of joint centers using kinematic constraints.
 
         Parameters
         ----------
@@ -38,8 +38,8 @@ def __init__(self, g=9.81, method='SAC', mask_input=True, min_samples=1000, mask
 
         References
         ----------
-        Crabolu et al. In vivo estimation of the shoulder joint center of rotation using magneto-inertial sensors:
-        MRI-based accuracy and repeatability assessment. BioMedical Engineering Online. 2017.
+        Crabolu et al. "In vivo estimation of the shoulder joint center of rotation using magneto-inertial sensors:
+        MRI-based accuracy and repeatability assessment." *BioMedical Engineering Online*. 2017.
         """
         self.g = g
         self.method = method
@@ -208,6 +208,7 @@ def _compute_distance_residuals(r, a1, a2, w1, w2, wd1, wd2):
 class KneeAxis:
     def __init__(self, mask_input=True, min_samples=1500, opt_kwargs=None):
         """
+        Estimation of the flexion/extension knee axis using kinematic constraints.
 
         Parameters
         ----------
@@ -220,9 +221,9 @@ def __init__(self, mask_input=True, min_samples=1500, opt_kwargs=None):
 
         References
         ----------
-        Seel et al. IMU-Based Joint Angle Measurement for Gait Analysis. Sensors. 2014
-        Seel et al. Joint axis and position estimation from inertial measurement data by exploiting kinematic
-        constraints. 2012 IEEE International Conference on Control Applications. 2012
+        Seel et al. "IMU-Based Joint Angle Measurement for Gait Analysis." *Sensors*. 2014
+        Seel et al. "Joint axis and position estimation from inertial measurement data by exploiting kinematic
+        constraints." *2012 IEEE International Conference on Control Applications*. 2012
         """
         self.mask_input = mask_input
         self.min_samples = min_samples
@@ -303,7 +304,7 @@ def _compute_axis_residuals(j, thigh_w, shank_w):
         return norm(wp1, axis=1) - norm(wp2, axis=1)
 
 
-def correct_knee(thigh_w, shank_w, thigh_r, shank_r, R_shank_thigh, knee_axis_kwargs={}):
+def correct_knee(thigh_w, shank_w, thigh_r, shank_r, R_shank_thigh, knee_axis_kwargs=None):
     """
     Correct the knee position based on the computed knee axis.
 
@@ -329,6 +330,8 @@ def correct_knee(thigh_w, shank_w, thigh_r, shank_r, R_shank_thigh, knee_axis_kw
     shank_r_corr : numpy.ndarray
         Corrected knee joint center to shank sensor vector.
     """
+    if knee_axis_kwargs is None:
+        knee_axis_kwargs = {}
     # compute the knee axis
     ka = KneeAxis(**knee_axis_kwargs)
     thigh_j, shank_j = ka.compute(thigh_w, shank_w)

diff --git a/pykinematics/imu/optimize/filters.py b/pykinematics/imu/optimize/filters.py
@@ -31,11 +31,6 @@ def __init__(self, x0, P0, F, H, Q, R):
         R : matrix_like,array_like,float,str,optional
             Process covariance.  Must be None, NxN matrix/array, or float.
             If None, defaults to 1.
-
-        Methods
-        -------
-        run(z, f_kwargs, h_kwargs, sigma_kwargs)
-            Run one step of the unscented kalman filter algorithm.
         """
 
         if x0.ndim == 1:
@@ -202,12 +197,6 @@ def __init__(self, x0, tol=0.001, f_tol=0.001, max_iters=300, verbose=False):
         verbose : bool, optional
             Display convergence messages on the first 10 iterations, and then on iterations that are perfect squares.
             Default is False
-
-        Methods
-        -------
-        fit(f, J, f_args={}, j_args={})
-            Perform the optimization using the function f to calculate the residuals, and J to calculate the Jacobian.
-            Extra arguments can be passed to f and J through f_args and j_args
         """
         self.tol = tol
         self.ftol = f_tol

diff --git a/pykinematics/imu/orientation/orientation.py b/pykinematics/imu/orientation/orientation.py
@@ -13,7 +13,7 @@
 from pykinematics.imu.optimize import UnscentedKalmanFilter
 
 
-__all__ = ['MadgwickAHRS', 'OrientationComplementaryFilter', 'SSRO', 'OldSROFilter']
+__all__ = ['MadgwickAHRS', 'OrientationComplementaryFilter', 'SSRO']
 
 
 class MadgwickAHRS:
@@ -31,9 +31,9 @@ def __init__(self, sample_period=1/256, q_init=array([1, 0, 0, 0]), beta=0.041):
             Beta value for the algorithm.  Default is 1.0
 
         References
-        ---------
-        S. Madgwick et al. "Estimation of IMU and MARG orientation using a gradient descent algorith." IEEE Intl. Conf. on
-        Rehab. Robotics. 2011.
+        ----------
+        S. Madgwick et al. "Estimation of IMU and MARG orientation using a gradient descent algorithm." *IEEE Intl.
+        Conf. on Rehab. Robotics*. 2011.
         """
         self.sample_period = sample_period
         self.q = q_init

diff --git a/pykinematics/omc/utility.py b/pykinematics/omc/utility.py
@@ -58,8 +58,8 @@ def default_marker_names():
     marker_names : pykinematics.omc.MarkerNames
         Object for storing the marker names and their associated label in the optical motion capture marker data.
     """
-    for key in MarkerNames.__dict__.keys():
-        print(f'{key}: {MarkerNames.__dict__[key]}')
+    for key in MarkerNames.__dataclass_fields__.keys():
+        print(f'{key}: {MarkerNames.__dataclass_fields__[key].name}')
 
     return MarkerNames