pyomeca/biorbd

Biomechanical add-ons to the RigidBody Dynamics Library

Pyomeca is a python library allowing you to carry out a complete biomechanical analysis; in a simple, logical and concise way.

Pyomeca documentation

See Pyomeca's documentation site.

Example

Pyomeca implements specialized functionalities commonly used in biomechanics. As an example, let's process the electromyographic data contained in this c3d file.

You can follow along without installing anything by using our binder server:

from pyomeca import Analogs

data_path = "../tests/data/markers_analogs.c3d"
muscles = [
    "Delt_ant",
    "Delt_med",
    "Delt_post",
    "Supra",
    "Infra",
    "Subscap",
]
emg = Analogs.from_c3d(data_path, suffix_delimiter=".", usecols=muscles)
emg.plot(x="time", col="channel", col_wrap=3)

emg_processed = (
    emg.meca.band_pass(order=2, cutoff=[10, 425])
    .meca.center()
    .meca.abs()
    .meca.low_pass(order=4, cutoff=5, freq=emg.rate)
    .meca.normalize()
)

emg_processed.plot(x="time", col="channel", col_wrap=3)

import matplotlib.pyplot as plt

fig, axes = plt.subplots(ncols=2, figsize=(10, 4))

emg_processed.mean("channel").plot(ax=axes[0])
axes[0].set_title("Mean EMG activation")

emg_processed.plot.hist(ax=axes[1], bins=50)
axes[1].set_title("EMG activation distribution")

See the documentation for more details and examples.

Features

• Signal processing routine commonly used in biomechanics such as filters, normalization, onset detection, outliers detection, derivatives, etc.
• Common matrix manipulation routines implemented such as getting Euler angles to/from a rototranslation matrix, creating a system of axes, setting a rotation or translation, transpose or inverse, etc.
• Easy reading and writing interface to common files in biomechanics (c3d, csv, xlsx,mat, trc, sto, mot)
• All of xarray's awesome features

The following illustration shows all of pyomeca's public API. An interactive version is available in the documentation.

Installation

Pyomeca itself is a pure Python package, but its dependencies are not. The easiest way to get everything installed is to use conda.

To install pyomeca with its recommended dependencies using the conda command line tool:

conda install -c conda-forge pyomeca

Now that you have installed pyomeca, you should be able to import it:

import pyomeca

Integration with other modules

Pyomeca is designed to work well with other libraries that we have developed:

• pyosim: interface between OpenSim and pyomeca to perform batch musculoskeletal analyses
• ezc3d: Easy to use C3D reader/writer in C++, Python and Matlab
• biorbd: C++ interface and add-ons to the Rigid Body Dynamics Library, with Python and Matlab binders.

Bug reports & questions

Pyomeca is Apache-licensed and the source code is available on GitHub. If any questions or issues come up as you use pyomeca, please get in touch via GitHub issues. We welcome any input, feedback, bug reports, and contributions.

Citing Pyomeca

If you use pyomeca in your academic work, please consider citing our paper as:

@article{Martinez2020,
  doi = {10.21105/joss.02431},
  url = {https://doi.org/10.21105/joss.02431},
  year = {2020},
  publisher = {The Open Journal},
  volume = {5},
  number = {53},
  pages = {2431},
  author = {Romain Martinez and Benjamin Michaud and Mickael Begon},
  title = {`pyomeca`: An Open-Source Framework for Biomechanical Analysis},
  journal = {Journal of Open Source Software}
}

Please consider citing the xarray project, which pyomeca is based on:

@article{jors-xarray,
title = {Xarray: N-D labeled arrays and datasets in Python},
author = {Joe Hamman and Stephan Hoyer},
year = {2017},
journal = {Journal of Open Research Software}
}

Contributors

• Romain Martinez
• Benjamin Michaud
• Mickael Begon
• Jenn Dowling-Medley
• Ariane Dang

Pyomeca is an open-source project created and supported by the S2M lab.

biorbd's Issues

Contact forces are not tested yet for ForwardDynamicsConstraintDirect with Casadi

In line 960 of test_rigidbody.cpp, the test named TEST(Dynamics, ForwardAccelerationConstraint) is incomplete for CasADi version.

Problem with biorbd.VecBiorbdMuscleStateDynamics.setActivation() income

Hi !

I installed the last version of rbdl with Casadi and biorbdl too (branch master and branch casadi. The two version are update with the version on github). I work on PyCharm editor (version 2019.3.3).

With this version, I can manipulate some function with MX argument, like the function biorbd.Model.ForwardDynamics(), which take in argument my state and my torque (in MX type), and give me back the derivation of my state.

I would like to use the function biorbd.VecBiorbdMuscleStateDynamics.setActivation() with MX argument too. But my editor send me this Error Message : "Wrong number or type of arguments for overloaded function 'StateDynamics_setActivation'." It is waiting for a double argument.

So, I look at in " biorbd/include/Muscles/StateDynamics.h " on github in Casadi branch for the setActivation function. It is waiting for " biorbd::utils::Scalar val ". In " biorbd/include/Utils/Scalar.h " (Casadi branch) the type of Scalar is define like this : "RigidBodyDynamics::Math::Scalar Scalar". In " rbdl-casadi/include/rbdl/rbdl_math.h " (branch master), the Scalar is define like this : "Vector1_t Scalar" and Vector1_t is define like this : "RBDLCasadiMath::MX_Xd_scalar Vector1_t".

So, logicaly, setActivation function can use MX argument. I think there is a problem so.

constraint degree of freedom

Hello,
It could be great if we could constraint one degree of freedom and/or link him to another one

SegmentCharacteristics class?

Although the "SegmentCharacteristics" class is listed in the documentation, it is missing for me. I want to SET the characteristics of a segment using python by segment.SegmentCharacteristics(mass, inertia, com), not RETURN them, which I can do by segm.characteristics().
Is this method deprecated?

Here is the doc link:
https://pyomeca.github.io/Documentation/biorbd/classbiorbd_1_1rigidbody_1_1SegmentCharacteristics.html

Multiple participants in a single c3d

I am interested in loading a c3d that has two participants with the same marker set to perform IK. Is this possible with biorbd as-is? Or should I export my c3d so that the two participants are in two different files and run IK for them separately? Thank you.

[REVIEW] Fix reference on JOSS Paper

I can't seem to find this article that you have in your references, do you have more information as to where it was presented?

Desmyttere, G., Hajizadeh, M., Bleau, J., & Begon, M. (2019). Foot orthosis with add-onrearfoot posting can alter foot kinematics. In.

For JOSS Review openjournals/joss-reviews#2562

Muscle tendon equilibrium

Missing sequences for funcction biorbd::utils::Quaternion::eulerDotToOmega

The only sequence implemented is xyz.

[REVIEW] C++ Compiling Help

I'm assuming the CMakeLists.txt in the examples folder is supposed to help compile the example c++ scripts.
When I try to run it, I get an error:

CMake Error at CMakeLists.txt:21 (add_dependencies):
  add_dependencies called with incorrect number of arguments

I think this is due to the $BIORBD_NAME variable not being defined. What is this variable supposed to represent, and what should I set it to? Should I also be defining the locations for the biorbd_LIBRARY and biorbd_INCLUDE_DIR in the CMakeLists.txt? And should I also be defining the locations for Eigen and rbdl includes?

I alternatively tried compiling with g++, and put in the biorbd, Eigen, and rbdl include libraries in the command line. Unfortunately I got the error "undefined reference to `biorbd::rigidbody::GeneralizedVelocity::~GeneralizedVelocity()'", repeated for multiple class:functions. Not sure if this an error on my end, or with how the class:functions are defined in biorbd.

Sorry if some of these questions are basic, I'm a little rusty on compiling my c++ scripts!

For JOSS review openjournals/joss-reviews#2562

Define segment with translations and quaternions

We can define segments with quaternion, but not with also translations.
Following error occur:
Traceback (most recent call last):
File "/home/user/Documents/PyCharm/plugins/python-ce/helpers/pydev/pydevd.py", line 1438, in _exec
pydev_imports.execfile(file, globals, locals) # execute the script
File "/home/user/Documents/PyCharm/plugins/python-ce/helpers/pydev/_pydev_imps/_pydev_execfile.py", line 18, in execfile
exec(compile(contents+"\n", file, 'exec'), glob, loc)
File "/home/user/Documents/Programmation/BiorbdOptim/examples/sandbox/examples_articleBioptim/BioptimPaperExamples/somersault/main.py", line 16, in
ocp = prepare_ocp_quaternion(root_folder + "/models/JeChMesh_RootQuat.bioMod", final_time=1.5, n_shooting=300)
File "/home/user/Documents/Programmation/BiorbdOptim/examples/sandbox/examples_articleBioptim/BioptimPaperExamples/somersault/somersault/ocp.py", line 187, in prepare_ocp_quaternion
biorbd_model = biorbd.Model(biorbd_model_path)
File "/home/user/anaconda3/envs/Dev_bioptim/lib/python3.9/site-packages/biorbd_casadi/biorbd.py", line 6050, in init
_biorbd_casadi.Model_swiginit(self, _biorbd_casadi.new_Model(*args))
RuntimeError: Reading of file "JeChMesh_RootQuat.bioMod" failed with the following error:
QRanges and number of dof must be equal
Element: segment, named: PelvisRot

Spatial vector.

Assert the size of Q

This could come with an optim flag so when it is activated, the asserts are skipped

[REVIEW] Improvements to MATLAB installation

From self-compiling on Windows with default, it looks like the MATLAB .mexw64 file is put in C:\Program Files\MATLAB{version}\toolbox, but this is not in the default MATLAB search path (at least with the R2020a version I'm running).

I would suggest putting a note in the MATLAB section of the documentation to ensure that the .mexw64 file is in the search path with the command:

oldpath = path;
path(oldpath, 'C:\Program Files\MATLAB\R2020a\toolbox\biorbd_matlab');

This allows biorbd to be found globally. I believe this has to be run every time MATLAB is restarted, unless this snipped is added to startup.m

If possible, I also think it would be a good idea to maintain a copy of the compiled MATLAB version of biorbd on MATLAB File Exchange. This increases visibility for biomechanics MATLAB users.

D drive

Path won't find the path for a file which is on a D drive

mesh file parameters

Would you be able to point me to some documentation on mesh support in biorbd? I wasn't sure if I was looking in the right places, but didn't see anything in the class files or old issues

I tried loading an .stl file and wasn't able to. I also have triangles saved as .obj files and those loaded successfully using meshfile .[filename.obj], but I was wondering if there's a way to scale/rotate/position them on the kinematic chain? In addition, is there a way to make the meshes oblique/solid colour?

If there's no specific way to rotate/scale the meshes, is there a way to turn on placeholder segments? I would like some lines to connect all the frame centres so it's a bit easier to see the whole body as it's moving.

Thank you.

add range into bioMod

Could also help to determine physiological ranges in biorbd-viz

Result of torque method need to be converted in MX to be used by ForwardDynamics* instead of staying in Vector type

MuscularJointTorque function, problem with Casadi argument

Hello there !

After the #96 issues, I have an other problem. So, I have the same characteristic than this issues : My operating system is Ubuntu (Linux), I work on PyCharm editor (version 2019.3.3), I am using the Python 3.7.6 binder. I compute this issue branch #97 and it solve my precedent problem with setActivation.

But now, I have the same problem with the function muscularJointTorque.
I show you an example :

model = biorbd.Model("/home/path_model")
Nb_Muscles = model.nbMuscleTotal()
Act = MX.sym('Act', Nb_Muscles)
w = [Act]
ubw = [1] * Nb_Muscles
lbw = [0] * Nb_Muscles
w0 = [0.5] * Nb_Muscles
State = MX.sym('St', model.nbQ() + model.nbQdot())
w = [Act]
ubw = [3.14] * (model.nbQ() + model.nbQdot())
lbw = [-3.14] * (model.nbQ() + model.nbQdot())
w0 = [0] * (model.nbQ() + model.nbQdot())
VecSDyn = biorbd.VecBiorbdMuscleStateDynamics(model.nbMuscleTotal())
act = MX.sym('act', 1, 1)
setAct = lambda vec,act : vec.setActivation(act)
for k in range(model.nbMuscleTotal()):
       setAct(VecSDyn[k], Act[k])
Result = model.muscularJointTorque(VecSDyn, State[:model.nbDof()], State[model.nbDof():])

And the error message is :

return _biorbd.Model_muscularJointTorque(self, state, Q, QDot)
TypeError: in method 'Model_muscularJointTorque', argument 3 of type 'biorbd::rigidbody::GeneralizedCoordinates const &'

My argument are Q and QDot, they are MX arguments and it is waiting for Generalized Coordinates. So, I look at in 'biorbd/include/RigidBody/GeneneralizedCoordinates.h, and because I use casadi-math (ligne 63, #ifdef BIORBD_USE_CASADI_MATH), it is waiting for MX casadi value.

I think so there is a problem. Think you for your future answers.

Tolerance difference between biorbd-casadi and biorbd-eigen for RT check

Error when trying to use BiorbdViz.BiorbdViz(model_path) with biorbd-eigen. No error when biorbd-casadi is used instead.

Traceback (most recent call last):
  File "/snap/pycharm-community/209/plugins/python-ce/helpers/pydev/_pydevd_bundle/pydevd_exec2.py", line 3, in Exec
    exec(exp, global_vars, local_vars)
  File "<input>", line 1, in <module>
  File "/home/andre/anaconda3/envs/KalmanFilter/lib/python3.8/site-packages/BiorbdViz/__init__.py", line 292, in __init__
    if sum([len(i) for i in self.model.meshPoints(np.zeros(self.model.nbQ()))]) > 0:
  File "/home/andre/anaconda3/envs/KalmanFilter/lib/python3.8/site-packages/biorbd/biorbd.py", line 3630, in meshPoints
    return _biorbd.Joints_meshPoints(self, *args)
RuntimeError: The Rotation matrix norm is not equal to one

Tolerance is probably too strict in biorbd-eigen.
If biorbd is compiled from source while setting SKIP_ASSERT to TRUE using CMAKE, no error is found.
Error occurs using a model with 42 DoFs, 17 segments and 95 markers.

RT matrix are transposed while writing models

Verify conversion from rotation matrix to euler angles

It seems that specific sequences like 'zy' might give sign errors.
Maybe a if can solve the problem.

Added muscle names in python interface

Better exceptions handling

Change the "assert"s to throws and handle the python interface using %typemap(throws)

Change the error returned for rotation matrix of norm not exaclty 3

Calculate the orthogonal matrix and return it to the user.

findDlib

For some reason, it says that it cannot find DLib while it obsously is

str python not accepted in place of biorbd::utils::String

For instance, using biorbd::utils::RotoTrans::transformMatrixToCardan(const RotoTrans& a, const biorbd::utils::String &seq) in python yields :

biorbd.RotoTrans().transformMatrixToCardan(biorbd.RotoTrans(),"xyz")

TypeError: in method 'RotoTrans_transformMatrixToCardan', argument 2 of type 'biorbd::utils::String const &'

Simplify the CasADi graph for muscles

Allow for activation outside 0 to 1

Variable with an e

Variables with an e are interpreted as xxx * 10^xxx instead of a single string

Add in bioMod non-crossing objects

See Eve's work

biorbd.Vector do not work with model.torque method

Fix model.CoMdot() and model.CoMddot()

• Missing get_array() method for model.CoMdot()

• model.CoMddot() broken : "RuntimeError: Com DDot is wrong, to be modified..."

Modify the plane of soft contacts in .bioMod

One could be interested in modifying the ground plane of contact in the global frame. For now, the point plane is (0, 0, 0) and the normal of the plane is (0, 0, 1).

Here is a list features that could be integrated :

1. The plane point associated to the plane of contact (easiest, modifying the altitude of the contact)
2. The normal vector of the plane of contact (need to transform the computation into the plane's frame)
3. The segment in which the plane is located (need to add another transformation into the segment's frame)

raise an error if RT in bioMod is not unitary

see the title

biorbd_model.nbGeneralizedTorque() counts 4 torques per quaternion

biorbd_model = biorbd.Model("TruncAndArm_Quaternion.bioMod" )
nq = biorbd_model.nbQ() -> 10
nqdot = biorbd_model.nbQdot() -> 9
ntau = biorbd_model.nbGeneralizedTorque() -> 10
TruncAndArm_Quaternion.txt

Wrapping class swig mapping issue

Hi, first of all, thanks a lot for the great library!

I've been using it for calculating the achievable force polytopes of a human arm, at the moment I'm working in python and I'm trying to translate the opensim models to the biorbd format. So, I'll need to include the wrapping of muscles in my models, and this seems to be well supported by the biorbd, which is great. 😄

But when the wrapping is enabled and if I try to visualize the model, using the bioviz, or just run the example provided in the libray I've got some issues of TypeError related to swig I think.

$ python Test_longueur_wrapping.py 
Traceback (most recent call last):
  File "/home/user/github/pyomeca/biorbd/examples/Test_longueur_wrapping.py", line 39, in <module>
    RTw = biorbd.WrappingHalfCylinder(model.muscle(0).pathModifier().object(0)).RT(
  File "/home/user/anaconda2/envs/pyomeca/lib/python3.9/site-packages/biorbd/biorbd.py", line 5855, in RT
    return _biorbd_eigen.WrappingHalfCylinder_RT(self, model, Q, updateKin)
TypeError: Wrong number or type of arguments for overloaded function 'WrappingHalfCylinder_RT'.
  Possible C/C++ prototypes are:
    BiorbdEigen3::muscles::WrappingHalfCylinder::RT(BiorbdEigen3::rigidbody::Joints &,BiorbdEigen3::rigidbody::GeneralizedCoordinates const &,bool)
    BiorbdEigen3::muscles::WrappingHalfCylinder::RT(BiorbdEigen3::rigidbody::Joints &,BiorbdEigen3::rigidbody::GeneralizedCoordinates const &)

I get the same error if I try to calculate the radius or lenght:

Traceback (most recent call last):
  File "/home/user/github/pyomeca/biorbd/examples/Test_longueur_wrapping.py", line 39, in <module>
    l = biorbd.WrappingHalfCylinder(model.muscle(0).pathModifier().object(0)).length()
  File "/home/user/anaconda2/envs/pyomeca/lib/python3.9/site-packages/biorbd/biorbd.py", line 5870, in length
    return _biorbd_eigen.WrappingHalfCylinder_length(self)
TypeError: in method 'WrappingHalfCylinder_length', argument 1 of type 'BiorbdEigen3::muscles::WrappingHalfCylinder const *'

Would you suggest me to build the project from source to avoid this error?
For now I've got the conda version of the biorbd and bioviz.
I've got swig SWIG Version 4.0.2 and python Python 3.9.5

Broken install in conda for biorbd-casadi and python3.7

When installing biorbd-casadi from conda-forge in python 3.7, the package is installed in /lib/python3.8/site-packages/
Moving the folder to python3.7/site-packages does not do the trick, there are some .so missing !

NoedeSegment method error

Hi guys,

First of all, thank you for this great tool that you have been developping ! I tried the testing file from your github and it works fine on my computer.

So I decided to go further and tried to develop my own model based on an old acquisition.

Everything works fine until these lines of code :

markersOverFrames = []
for i in range(markers.shape[2]) :
markersOverFrames.append([biorbd.NodeSegment(m) for m in markers[:, :, i].T])

I get this error message :

TypeError: Wrong number or type of arguments for overloaded function 'new_NodeSegment'.
Possible C/C++ prototypes are:
biorbd::rigidbody::NodeSegment::NodeSegment()
biorbd::rigidbody::NodeSegment::NodeSegment(biorbd::utils::Scalar const &,biorbd::utils::Scalar const &,biorbd::utils::Scalar const &)
biorbd::rigidbody::NodeSegment::NodeSegment(biorbd::utils::Vector3d const &)
biorbd::rigidbody::NodeSegment::NodeSegment(biorbd::utils::Scalar const &,biorbd::utils::Scalar const &,biorbd::utils::Scalar const &,biorbd::utils::String const &,biorbd::utils::String const &,bool,bool,biorbd::utils::String const &,int)
biorbd::rigidbody::NodeSegment::NodeSegment(biorbd::utils::Vector3d const &,biorbd::utils::String const &,biorbd::utils::String const &,bool,bool,biorbd::utils::String const &,int)

Do you have insights of how to resolve it ?

Thanks for letting me know

regards

Emmanuel AYAD

Adds .bioMod path in Model

All in the title !

File reader error returns an issue with version not found instead of file not found

biorbd couldn't read my .ply mesh file

Please find below the mesh file that couldn't be read with biorbd. The issue may be resolvable examining the ply reader.

my meshfile

Also, some mesh files could have extensions in uppercase characters, e.g. .PLY, .STL, .VTP. It could be added to avoid troubles to the users.

fPIC

Dlib lib needs to be compiled with fPIC. It should be the default value in the CMakeLists.txt

Problem with actuators

Biorbd functions to get torque activations from actuators in .bioMod and to compute torques from activation, q and q_dot are not accessible from Python.

Visual Studio Error: LNK2019 Unresolved External Symbol

• Examples no longer build in VS Release Configuration after messing around with rbdl add-ons
  biorbd_eigen.lib(ModelReader.obj) : error LNK2019: unresolved external symbol
• Executable no longer generated
• Update: Gave up on Windows & went to Mac. Works beautifully

Documentation

Could you provide a documentation on biorbd functions.
Thank you

Add interface to set initial solution for Kalman Filter reconstruction in Python

Function to set initial solution for Kalman Filter reconstruction is not available in Python

version of biorbd

call version return ".."

Passive torque

Based on Actuators using exponential or high order polynomials

Allow external forces for segment without DoF

• or raise an error to notify the user

[REVIEW] Not able to run staticOptimization example for Python

With the latest version from conda-forge I get the error:

Traceback (most recent call last):
  File "staticOptimization.py", line 38, in <module>
    optim = biorbd.StaticOptimization(model, Q, Qdot, Tau)
AttributeError: module 'biorbd' has no attribute 'StaticOptimization'

when running the staticOptimization.py Python example. I'm assuming the conda-forge version is using Eigen, which means this should be possible?

for JOSS Review openjournals/joss-reviews#2562

Need CompositeRigidBodyAlgorithm() and InverseDynamics() for c# code

Need to use these 2 fonctions in my c# code linked to Unity.