chrisdembia / yeadon

The human inertia model developed by Fred Yeadon in 1990.

yeadon

This package calculates the masses, center of mass positions, and inertia tensors that correspond to the human inertia model developed by Yeadon in (Yeadon, 1990). The package allows for the input of both measurements and configuration variables (joint angles), and provides 3D visualization using the MayaVi package. See the online documentation at http://yeadon.readthedocs.org/.

References

M. R. Yeadon, 1990. The Simulation of Aerial Movement-ii. Mathematical Inertia Model of the Human Body. Journal of Biomechanics, 23:67-74.

Directories

• yeadon/ contains the python source files for the yeadon package.
• doc/ contains source documents for building sphinx documentation.
• misc/ contains figures and template input files.
• misc/samplemeasurements/ contains sample measurement input files.

Installing

This package was developed for Python 3.7+.

Dependencies

yeadon depends on the following widely-used packages:

• setuptools for installation
• NumPy for computations
• PyYAML for parsing input files

The following packages are optional:

• MayaVi for visualization and GUI interaction
• nose for tests
• Sphinx to create documentation
• numpydoc Sphinx extension for NumPy-style documentation formatting

Getting the dependencies

Option 1: Scientific python distributions

Most scientific python distributions provide all of these dependencies and it is often easiest to install one of them to get started. Once you have a distribution, you can install the yeadon package. This is the best solution for Windows users.

Option 2: Operating system package manager

In some operating systems, the dependencies can also be obtained from the operating system's package manager. For example, in Debian systems, you should be able to obtain all of these packages by opening a terminal window and typing:

$ # prepend sudo to each line below if you desire a system install
$ apt-get install python3-setuptools python3-numpy python3-yaml # required
$ apt-get install python3-nose python3-sphinx python3-numpydoc mayavi2 # optional packages

For other operating systems (e.g. Windows or Mac), visit the websites for the packages for installation instructions.

Option 3: Building dependencies from source

This option is required if you want to use yeadon in a virtualenv. You can build the dependencies from source and then install them by using a tool like pip:

$ python -m pip install numpy PyYAML
$ python -m pip install nose sphinx mayavi
$ python -m pip install numpydoc

or you can obtain the source code, perhaps from GitHub, and install the packages manually.

Getting yeadon

Once you've obtained the dependencies, you can install yeadon. The easiest way to download and install the yeadon package is by using a tool like pip to obtain the package from the Python Package Index (PyPi):

$ python -m pip install yeadon # sudo if system install

You can also obtain an archive of the package at the Python Package Index (https://pypi.python.org/pypi/yeadon), and then install the package on your own by executing the following from the root directory of the package:

$ python setup.py install # sudo if system install

On Unix, you can obtain the package source code and install it without leaving your terminal:

$ # change X.X.X to the desired version
$ wget https://pypi.python.org/packages/source/y/yeadon/yeadon-X.X.X.tar.gz
$ tar -zxfv yeadon-X.X.X.tar.gz
$ cd yeadon-X.X.X.tar.gz
$ python setup.py install # sudo if system install

Run the tests with:

$ python setup.py nosetests

Building the documentation

You can build the yeadon HTML documentation if you have Sphinx by typing the following from the root directory of the yeadon source files:

$ cd doc/
$ make html

You can open the documentation in your favorite web browser:

$ firefox _build/html/index.html

If you have a LaTeX distribution installed you can build the LaTeX docs with:

$ cd doc/
$ make latexpdf

and view the document with your preferred PDF viewer:

$ evince _build/latex/yeadon.pdf

Note that to generate documentation, one also needs the numpydoc package. Alternatively, one can just access the documentation through the PyPi site.

Usage

Once the package is installed you can start the program with:

$ yeadon

If you have MayaVi installed, the GUI will launch. If you don't, the text based UI will launch. You can explicitly specify whether you want to load the GUI or the UI with command-line flags:

$ yeadon --gui
$ yeadon --ui

You can also interact with yeadon in a Python interpreter session or Python script/module via the API by importing the package. For example:

$ python
>>> import yeadon

Now you can create a human object with:

>>> human = yeadon.Human(<measfilename>, <CFGfilename>)

where <measfilename> and <CFGfilename> are replaced by strings that contain a relative or absolute path to the appropriate input .txt files. For more basics on how to use a Human object, you can go into a python command prompt and type:

>>> help(yeadon.Human)

or see the documentation.

You can also start the UI or the GUI from within a Python interpreter by executing:

>>> yeadon.start_ui()

or:

>>> yeadon.start_gui()

See the documentation for more information.

Cite us!

If you make use of the yeadon software we would welcome a citation in your publications. Please cite this software paper:

Dembia C, Moore JK and Hubbard M. An object oriented implementation of the Yeadon human inertia model, F1000Research 2014, 3:223 (doi: https://dx.doi.org/10.12688/f1000research.5292.1)

Contact

Feel free to contact Chris Dembia (chris530d, gmail) with any questions or comments.

All development is handled at http://github.com/chrisdembia/yeadon, including issue tracking.

yeadon's Issues

push bug fixes to pypi

Chris,

I think you should push a bug fix version up to PyPi with the latest commits.

Jason

Euler angles?

When I play with the elevation angle of the upper arm (shoulder joint) in the GUI it seems like it is defined as a Space fixed coordinate instead of a Body Fixed. I though that Yeadon used Euler Angles (Body Fixed) for every thing. We should check this.

Reset configuration

Thigh abductions/elevation bug

Two things:

1. If you set the abduction and flexion angles for the thigh:

PJ1flexion=2.3
PJ1abduction=1.7

Then you get an elevation and a rotation instead of a elevation and abduction.

1. The thigh flexion should be named elevation...I think. Your variable name in the CFG input file is different than the one from the nice diagrams you made.

The mass scaling doesn't always work.

Sometimes the mass scaling gives me this error:

Error: attempted to scale mass by a measured mass, but did not succeed. Measured mass: 78.75 self.Mass: 78.74

But for the same calculation, it may work fine. I'm not sure why this is happening.

Why does measurements.py?

Why?

Double-check that the configuration is specified using YAML syntax.

We need tests

We need to have test coverage so that we don't break stuff when we make changes. Just a reminder.

Update the README in general.

Documentation improvement

• More clearly explain how the package is used (whether through the command line or the "API"). Make the distinction between configuration and state.
• Make it clear that measurements (L*) are all lengths.
• Reflect the new mayavi dependency in the README and the setup.py file.
• Replace stadium figure with PGF figure of the paper.

Getting inertia tensor of the human in a different basis

-We talked about how nice it would be to have an inertia(about=None, in_frame=None) method where the user can get the inertia dyadic about some other frame etc.

-We also want the user to be able to transform the inertia tensor in the GUI, so the user provides a point and a rotation matrix used to transform the inertia tensor in the GUI.

-There's a separate issue of using the current visualization in one's other visualization. So combining yeadon library draw_mayavi() as part of some other code. We could either AVOID modifying yeadon at all, and just set transformations in mayavi itself, but then what does the inertia tensor represent? How do we know its rotation?

some documentation on segment position is needed in the doc usage.rst

is H.J1.pos to the center of mass of that segment?

Order of rotations

It seems there may be some guidance for the order of rotations for multi-DOF joints from the International Society of Biomechanics:

main page:
http://isbweb.org/information-services/standards

example for the ankle and others.
http://isbweb.org/images/stories/documents/standards/isb_jcs_part_i.pdf

Perhaps we should both look at this stuff and decide if it's what we want to do. I haven't looked at it in detail yet, but it seems it shouldn't be too bad.

bug in UI c: combine solids/segments for inertia parameters

when I use the combine solids/segments option in the ui, I can enter the solids I want to but when I enter "q", I just get a newline and cannot exit the menu.

Replace vpython with mayavi

Principal axes in the visualization

It would be nice to display either principal axes or an inertia ellipsoid in the 3D visualization.

Update the language to be more precise about reference frames, etc.

Inertia matrices/dyadics require a point and a frame, center of mass point requires a frame. If we really want to get fancy, we could create a reference frame class.

Clean up configuration sliders

Make a GUI!

• Have sliders to change configuration, show inertia ellipse. Have tabs to give out all the data.
• Make MayaVi rendering fancier: show center of mass ball, direction vectors, etc.
• Make a screencast using RecordMyDesktop

http://docs.enthought.com/mayavi/mayavi/building_applications.html

Thigh elevation or flexion?

Here we have PJ1elevation, PK1elevation:

http://pythonhosted.org/yeadon/configuration.html

But in the code we have PJ1flexion, PK1flexion:

https://github.com/chrisdembia/yeadon/search?q=PJ1flexion&ref=cmdform

Easiest to fix would be the documentation I suppose. Is it supposed to be elevation or flexion?

Impossible Stadium definitions

When trying to define a Stadium with a thickness/radius too large for the perimeter, etc (an impossible stadium), we define a circle with the corresponding perimeter instead.

This is an issue for female1.txt.

Old style non yaml file on pypi

This file:

http://pythonhosted.org/yeadon/_downloads/meastemplate.txt

has equals signs instead of colons.

GUI screencast script

Hi I'm Chris and I'm going to show you a python package called Yeadon that we've made. The package allows one to estimate the inertial properties of a human using 95 measurements. Such information could then be used in research studying human movement. The model was developed by Fred Yeadon when he was a graduate student in the late 1980s studying gymnastics. We've employed his work to help us explore bicycle mechanics. In order to make his work widely accessible and to promote collaboration in biomechanics research, we have implemented his model in a Python package and have made it available to all through the Python Package Index (https://pypi.python.org/pypi/yeadon/0.8) and on the website GitHub.

There are a few ways to use the Yeadon python package. In this video we are only going to show one of these: the graphical user interface, or GUI. The intent of this video is not to make you fluent in the use of the python package, but rather to show what you can do with it. For more details on how to use its features, you can visit the documentation for the package at the Python Package Index.

1. Load measurements (mass scaling or not).
2. Observe inertia properties.
3. Alter configuration variables, observe change in inertia properties.
4. Toggle view of center of mass, inertia ellipsoid, reference frame basis vectors, segmental reference frame basis vectors (explain the utility of viewing the basis vectors).
5. Saving a configuration.

GUI launching

How do we want the GUI to be launched? Some options are:

1. In bash, running something like

   $ ipython yeadon/gui.py

2. In a python shell, running something like

   import yeadon
   yeadon.start_gui()
   yeadon.start_gui('measfile.txt')

3. As a method in the Human object:

   import yeadon as y
   h = y.Human()
   h.start_gui()

4. Others?

1's pro's: It runs more like an application this way, doesn't require you to be in a python shell. con's: Requires you to know where the yeadon module is actually located on your machine, rather than relying on it being on the path for importing.

2: swap the pro's and con's from 1.

3: This is a question of whether the gui wraps the human or vice versa, and I think the gui should wrap the human; there should be no need to have mayavi if GUI usage is not desired.

I'm going to go with 2 for now, which is what we have for the UI.

NumPy doesn't install correctly with our setuptools dependency

If you have a clean virtualenv and all of the dependencies for numpy installed globally, python setup.py install of the yeadon package fails when trying to obtain the numpy dependency. But pip install numpy works just fine.

Location of hip joint centres.

Yeadon has suggested that the lateral distance between the hip joint centres and the center of the Ls0 level should be

.5r + .5t

where r and t are the radius and thickness of the Ls0 stadium. Currently, this lateral distance is t.

Jason do you support changing t to .5r + .5t?

Test that docs build on clean install

Make sure there are no warnings and that the manifest.in has pulled in all of the files.

should rotate3 and euler_123 return the transpose of what you are returning?

Your rotate3 function is actually an Euler angle convention: 1-2-3 (x-y-z)

and your euler_123 is named wrong (sorry bout that). it's euler convention is actually: 3-2-1 (z-y-x)

The thing I find weird is what version of the rotation matrix your functions return. Assuming two frames A and B, you could either output the rotation matrix of A with respect to B or B with respect to A.

Let's assume B is rotated in A. So if I have a vector, v, in reference frame A and want to know how to express v in reference frame B which has been rotated relative to A with Euler 1-2-3. Convention would be to define the rotation matrix, R, as:

v' = R * v

where v is the vector expressed in A and and v' is the same vector expressed in reference frame B.

If we assume the definition of R, v and v' as I described and you desire to have Euler 123 and Euler 321 then your functions return R transposed instead of R.

This may have a consequence when you rotate inertia tensors with rotate3_inertia, because you use:

I' = R * I * R^T

R in this equation should be defined as I have here, for this to inertia rotation to be correct.

I think that your overall code may be consistent with itself but these basics are confusing, except we need to check the inertia rotation. And you doc for rotate3 that explains the rotations doesn't seem correct. Both of your rotations are euler type of rotations. And you use the inertia rotation in rotate3_inertia like you've calculated R, but I think you may be calculating R transposed.

A nice book that has all this is: http://ecommons.cornell.edu/handle/1813/637 check out the tabulated values for all type of rotations in the Appendices starting on page 422. As far as I can tell your rotation functions are all body fixed rotations not space fixed. You described your rotate3 function as space fixed in the docs.

I just wrote a nice function dtk.inertia.euler_rotation that returns rotation matrices as I described. Check it out.

Refine API

• Replace the word "relative" (for relative mass/COM/moment of inertia), with "local".
• Hide (with prepended underscore) methods that we do not expect the user to use. This is particularly necessary for define* methods in Human, and any helper functions for drawing.
• Use exceptions for errors.

Resolve TODO's in tests

Somersault is mispelled

Somersalt should be somersault:

https://github.com/chrisdembia/yeadon/search?q=somersalt&type=Code

Load measurement file using the GUI

Remove PDF form and measpdf2txt.py

I think I want to remove the measform.PDF measpdf2txt.py files from the project. This allowed a user to fill out a PDF form, and extract the measurements from the form into a text file using measpdf2txt.py. The feature isn't that clean and is not tested. It's easy enough to directly enter the measurements into a text file. I think it would just be simpler to delete these files. I've actually gone ahead and done so already but will gladly ressurrect them if @moorepants thinks we should.

Ideally we'd make a simple web form but I am not willing to sink time into figuring that out.

GUI doesn't look so good with the wxpython backend in MayaVi

The background is dark and the font colors for the text are dark. Maybe there are some default settings that would make it look better.

ipython closes after the draw command is issued to the human object

I'm using yeadon with the bicycle parameters and when I tell the human to draw via visual python and then close the vpython window, the command line returns to bash and shuts down ipython. I have this in my yeadonwork branch if you want to try.

import bicycleparameters.bicycleparameters as bp
rigid = bp.Bicycle('Rigidfakeyeadon', forceRawCalc=True)
rigid.add_rider('Jason', 'data', draw=True)

then close the vpython window. this may be something wrong with vpython and its compatibility with ipython

Move the shoulder joint location inward

Currently the shoulder joint is location on the outer perimeter of Ls4. If the width of Ls4 is measured at the outer dimension of the shoulders (versus from shoulder joint to shoulder joint), then I think this is true. But if the width of Ls4 is measured from the shoulder joint to shoulder joint center then the current implementation is correct. Any idea what we should be doing with the width measurement?

Dependencies for pypi

We should make use of setuptools dependencies arguments so that everything gets installed from pip that needs to be. It may be possible to ensure that everything is installed correctly by only issuing "pip install yeadon" or "python setup.py install".

Re-ordering of Segment.solids not taken care of in segment.py

When we create solids, we now do so in reverse order. This may have unintended consequences in segment.py, where we assume that solids[0] is the root solid of a segment, and that solids[-1] is the most distal solid of the segment. I'll look into this later tonight hopefully.

The fix may be easy; it might just be re-reversing the order of the solids just before they're passed to the Segment constructor. I haven't looked into this in much depth, so I probably don't understand the issue yet.

I discovered this while trying to write tests for combine_inertia.
@moorepants

version number in __init__.py

We should add __version__ in the main __init__.py file. You can then use this version in the sphinx docs, setup.py, etc. But most importantly if I load yeadon in a script or session you can type yeadon.__version__ to know what version you imported. NumPy, SciPy, etc and most other packages have this variable available.

Make make_pos methods in solid more efficient.

the ui needs better error handling

If you mis type the name of the input to the first two questions in the UI, the ui fails. It'd be nice if if handled the error and let you retype your mistype.

There is no README.rst in the PyPi tarball

I thought I fixed this before, but the MANIFEST.in must need a reference to README.rst or *.rst.

This causes an installation fail when running setup.py from the PyPi download.

Test yeadon.human.combine_inertia()

Delete the archive directory

Can we delete this?

The only way to visualize is MayaVi

Get rid of matplotlib, etc.

update_segments should update the 3D image

If you call human.draw_visual() then change the joint angles, these should be reflected in the 3D visualization. Currently, you have to call draw_visual again and it just creates a new person on top of the old person.

Play around with UI to look for bugs.

Tags and PyPi

Chris,

We should make use of git tags to pin release versions that you push to PyPi. If you tag the commit that corresponds to a version, then we can easily tell how far master is ahead of the version on PyPi. I think the PyPi currently has some fatal bugs, like the no README one.

Jason

test_shoulder_rotation test fails

The test_human.Test_Human.test_shoulder_rotation() test fails. The values in the rotation matrix comparison are correct, but the signs of some terms are different. I'm not sure if this was caused by my merge; I changed the names of the endpos and rot_mat attributes to end_pos and _rot_mat (rot_mat is hidden for solids).

Why does measurements.py?

Why?