MuscleForceDirection / Git / Diff of /README.md

Models:

JoelW/

MuscleForceDirection

Downloads: 1

Diff of /README.md [b87f69] .. [717926]

Switch to unified view


![visitors](https://visitor-badge.laobi.icu/badge?page_id=modenaxe.muscleforcedirection)
# Overview

The Muscle Force Direction plugin extends the functionalities of [OpenSim](https://simtk.org/projects/opensim/) providing a straighforward interface to extract the muscle lines of action.
The source code of the plugin is provided in the main repository and a dll that can be loaded through the main OpenSim user interface is available through the `Releases` tab. 
Leveraging the OpenSim Application Programming Interface (API), we also provide MATLAB scripts that replicate the plugin functionalities.

# Background

If you are using the internal forces estimated by musculoskeletal models as load sets in finite element models you find that you have few options to compute the direction of each force vector:
1. use a PointKinematics analysis on the points of interest of your line of action, compute the force versor for the kinematic frame of interest
2. use the PointForceDirection class and search for the segment of the muscle line of action that you are interested in.

The `MuscleForceDirection plugin` (`MFD` plugin for short) tries to streamline this operations and make easier to extract muscle forces and apply them to finite element models.

![FE_workflow](https://github.com/modenaxe/MuscleForceDirection/blob/master/images/plugin_workflow.png?raw=true)

## "Anatomical" versus "Effective" lines of action

Anatomical muscle lines of actions are those whose attachments are on the bones.

Effective muscle lines of actions are those determining the effective mechanical
effect of the muscle action on the equilibrium of the bone when considering its
free body diagram.

A typical example is a muscle including _via points_ or _wrapping surface_, for
example the gastronemius, that can alter the muscle lines of action
substantially between the first segment of the muscle and the last segment
attached to a certain bone.
![anat_vs_effect](https://github.com/modenaxe/MuscleForceDirection/blob/master/images/anatomical_vs_effective.png?raw=true)

A good explanation of this difference is available in section 5.4.3 of Yamaguchi's book `Dynamic Modeling of Musculoskeletal Motion: A Vectorized Approach for Biomechanical Analysis in Three Dimensions` entitled `EFFECTIVE ORIGIN AND INSERTION POINTS`.

# Plugin options

Using the plugin setup you can decide:

1. the body/bodies of interest on which to run the MFD analysis
2. the reference system in which you want to express the line of actions
3. choose if you want to extract the "anatomical" lines of action or the "effective" lines of action.

# Installation
* For compiling the C++ plugin, follow the instructions available on the [OpenSim Developers' Guide](https://simtk-confluence.stanford.edu/display/OpenSim/Developer%27s+Guide), where you can also find some examples.
* For installing the MFD plugin for use in the OpenSim GUI follow the same procedure to install other plugins:
    * place the plugin in the `plugins` folder
    * restart OpenSim
* For using the MATLAB scripts (OpenSim version ), you need to:
    * ensure that the OpenSim API are correctly installed. Please refer to the OpenSim [documentation](https://simtk-confluence.stanford.edu/display/OpenSim/Scripting+with+Matlab).
    * include the MATLAB folder in your path.
    * check the provided examples.

# [WORK IN PROGRESS] Examples of use 

There will be examples of how to call the plugin from Matlab etc.


# Publications

The plugin was originally described in the Appendix of [this open access publication](https://github.com/modenaxe/MuscleForceDirection/blob/master/doc/papers/van%20Arkel%20et%20al.%20J%20Orthop%20Res%202013.pdf):

```bibtex
@article{van2013hip,
title={Hip abduction can prevent posterior edge loading of hip replacements},
author={van Arkel, Richard J and Modenese, Luca and Phillips, Andrew TM and Jeffers, Jonathan RT},
journal={Journal of Orthopaedic Research},
volume={31},
number={8},
pages={1172--1179},
year={2013},
publisher={Wiley Online Library}
}
```

but a better example of use is provided in this other open access [paper](https://github.com/modenaxe/MuscleForceDirection/blob/master/doc/papers/Phillips%20et%20al.%20Inter%20Biomech%202015.pdf):

```bibtex
@article{phillips2015femoral,
title={Femoral bone mesoscale structural architecture prediction using musculoskeletal and finite element modelling},
author={Phillips, Andrew TM and Villette, Claire C and Modenese, Luca},
journal={International Biomechanics},
volume={2},
number={1},
pages={43--61},
year={2015},
publisher={Taylor \& Francis}
}
```

# How to contribute

Feel free of contributing as by standard [GitHub
workflow](https://guides.github.com/activities/forking/):

1. forking this repository
2. creating your own branch, where you make your modifications and improvements
3. once you are happy with the new feature you have implemented create a pull
   request

## Resources for learning how to contribute
* If you want to contribute but you are not familiar with [Git](https://git-scm.com/), the [Software Carpentry Lessons](https://swcarpentry.github.io/git-novice/) are a perfect place to start with Git and GitHub.
* If you know how to use git but you are not familiar with GitHub, you can check resources like ["First Contributions"](https://github.com/firstcontributions/first-contributions) to learn how to contribute to existing projects.

# Resource on combining finite element and musculoskeletal models
* OpenSim Webinar: ["Interfacing Musculoskeletal and Finite Element Models to Study Bone Structure & Adaptation"](https://www.youtube.com/watch?v=0e6vQV_ioCI)

# Contributors
Several researchers have contributed to this package:
* [Luca Modenese](https://github.com/modenaxe): C++, Matlab
* [John J. Davis IV](https://github.com/johnjdavisiv): Plugin Matlab demo updated to OpenSim 4.2
* [Ke Song](https://github.com/KSongGitHub): Matlab update to OpenSim 4.0
* [Dimitar Stanev](https://github.com/mitkof6): C++ update to OpenSim 4.0
* [Claudio Pizzolato](https://github.com/cpizzolato): C++ makefiles
* [Friedl De Groote](https://github.com/FriedlDeGroote): C++ legacy [version](https://github.com/modenaxe/MuscleForceDirection/tree/master/CPP/legacy_code/OpenSim2.4_KULeuven) of v1.0
* Alfred Thibon: C++

	a/README.md		b/README.md
1	![visitors](https://visitor-badge.laobi.icu/badge?page_id=modenaxe.muscleforcedirection)	1	![visitors](https://visitor-badge.laobi.icu/badge?page_id=modenaxe.muscleforcedirection)
2	# Overview	2	# Overview
3		3
4	The Muscle Force Direction plugin extends the functionalities of [OpenSim](https://simtk.org/projects/opensim/) providing a straighforward interface to extract the muscle lines of action.	4	The Muscle Force Direction plugin extends the functionalities of [OpenSim](https://simtk.org/projects/opensim/) providing a straighforward interface to extract the muscle lines of action.
5	The source code of the plugin is provided in the main repository and a dll that can be loaded through the main OpenSim user interface is available through the `Releases` tab.	5	The source code of the plugin is provided in the main repository and a dll that can be loaded through the main OpenSim user interface is available through the `Releases` tab.
6	Leveraging the OpenSim Application Programming Interface (API), we also provide MATLAB scripts that replicate the plugin functionalities.	6	Leveraging the OpenSim Application Programming Interface (API), we also provide MATLAB scripts that replicate the plugin functionalities.
7		7
8	# Background	8	# Background
9		9
10	If you are using the internal forces estimated by musculoskeletal models as load sets in finite element models you find that you have few options to compute the direction of each force vector:	10	If you are using the internal forces estimated by musculoskeletal models as load sets in finite element models you find that you have few options to compute the direction of each force vector:
11	1. use a PointKinematics analysis on the points of interest of your line of action, compute the force versor for the kinematic frame of interest	11	1. use a PointKinematics analysis on the points of interest of your line of action, compute the force versor for the kinematic frame of interest
12	2. use the PointForceDirection class and search for the segment of the muscle line of action that you are interested in.	12	2. use the PointForceDirection class and search for the segment of the muscle line of action that you are interested in.
13		13
14	The `MuscleForceDirection plugin` (`MFD` plugin for short) tries to streamline this operations and make easier to extract muscle forces and apply them to finite element models.	14	The `MuscleForceDirection plugin` (`MFD` plugin for short) tries to streamline this operations and make easier to extract muscle forces and apply them to finite element models.
15		15
16	![FE_workflow](https://github.com/modenaxe/MuscleForceDirection/blob/master/images/plugin_workflow.png)	16	![FE_workflow](https://github.com/modenaxe/MuscleForceDirection/blob/master/images/plugin_workflow.png?raw=true)
17		17
18	## "Anatomical" versus "Effective" lines of action	18	## "Anatomical" versus "Effective" lines of action
19		19
20	Anatomical muscle lines of actions are those whose attachments are on the bones.	20	Anatomical muscle lines of actions are those whose attachments are on the bones.
21		21
22	Effective muscle lines of actions are those determining the effective mechanical	22	Effective muscle lines of actions are those determining the effective mechanical
23	effect of the muscle action on the equilibrium of the bone when considering its	23	effect of the muscle action on the equilibrium of the bone when considering its
24	free body diagram.	24	free body diagram.
25		25
26	A typical example is a muscle including _via points_ or _wrapping surface_, for	26	A typical example is a muscle including _via points_ or _wrapping surface_, for
27	example the gastronemius, that can alter the muscle lines of action	27	example the gastronemius, that can alter the muscle lines of action
28	substantially between the first segment of the muscle and the last segment	28	substantially between the first segment of the muscle and the last segment
29	attached to a certain bone.	29	attached to a certain bone.
30	![anat_vs_effect](https://github.com/modenaxe/MuscleForceDirection/blob/master/images/anatomical_vs_effective.png)	30	![anat_vs_effect](https://github.com/modenaxe/MuscleForceDirection/blob/master/images/anatomical_vs_effective.png?raw=true)
31		31
32	A good explanation of this difference is available in section 5.4.3 of Yamaguchi's book `Dynamic Modeling of Musculoskeletal Motion: A Vectorized Approach for Biomechanical Analysis in Three Dimensions` entitled `EFFECTIVE ORIGIN AND INSERTION POINTS`.	32	A good explanation of this difference is available in section 5.4.3 of Yamaguchi's book `Dynamic Modeling of Musculoskeletal Motion: A Vectorized Approach for Biomechanical Analysis in Three Dimensions` entitled `EFFECTIVE ORIGIN AND INSERTION POINTS`.
33		33
34	# Plugin options	34	# Plugin options
35		35
36	Using the plugin setup you can decide:	36	Using the plugin setup you can decide:
37		37
38	1. the body/bodies of interest on which to run the MFD analysis	38	1. the body/bodies of interest on which to run the MFD analysis
39	2. the reference system in which you want to express the line of actions	39	2. the reference system in which you want to express the line of actions
40	3. choose if you want to extract the "anatomical" lines of action or the "effective" lines of action.	40	3. choose if you want to extract the "anatomical" lines of action or the "effective" lines of action.
41		41
42	# Installation	42	# Installation
43	* For compiling the C++ plugin, follow the instructions available on the [OpenSim Developers' Guide](https://simtk-confluence.stanford.edu/display/OpenSim/Developer%27s+Guide), where you can also find some examples.	43	* For compiling the C++ plugin, follow the instructions available on the [OpenSim Developers' Guide](https://simtk-confluence.stanford.edu/display/OpenSim/Developer%27s+Guide), where you can also find some examples.
44	* For installing the MFD plugin for use in the OpenSim GUI follow the same procedure to install other plugins:	44	* For installing the MFD plugin for use in the OpenSim GUI follow the same procedure to install other plugins:
45	* place the plugin in the `plugins` folder	45	* place the plugin in the `plugins` folder
46	* restart OpenSim	46	* restart OpenSim
47	* For using the MATLAB scripts (OpenSim version ), you need to:	47	* For using the MATLAB scripts (OpenSim version ), you need to:
48	* ensure that the OpenSim API are correctly installed. Please refer to the OpenSim [documentation](https://simtk-confluence.stanford.edu/display/OpenSim/Scripting+with+Matlab).	48	* ensure that the OpenSim API are correctly installed. Please refer to the OpenSim [documentation](https://simtk-confluence.stanford.edu/display/OpenSim/Scripting+with+Matlab).
49	* include the MATLAB folder in your path.	49	* include the MATLAB folder in your path.
50	* check the provided examples.	50	* check the provided examples.
51		51
52	# [WORK IN PROGRESS] Examples of use	52	# [WORK IN PROGRESS] Examples of use
53		53
54	There will be examples of how to call the plugin from Matlab etc.	54	There will be examples of how to call the plugin from Matlab etc.
55		55
56		56
57	# Publications	57	# Publications
58		58
59	The plugin was originally described in the Appendix of [this open access publication](https://github.com/modenaxe/MuscleForceDirection/blob/master/doc/papers/van%20Arkel%20et%20al.%20J%20Orthop%20Res%202013.pdf):	59	The plugin was originally described in the Appendix of [this open access publication](https://github.com/modenaxe/MuscleForceDirection/blob/master/doc/papers/van%20Arkel%20et%20al.%20J%20Orthop%20Res%202013.pdf):
60		60
61	```bibtex	61	```bibtex
62	@article{van2013hip,	62	@article{van2013hip,
63	title={Hip abduction can prevent posterior edge loading of hip replacements},	63	title={Hip abduction can prevent posterior edge loading of hip replacements},
64	author={van Arkel, Richard J and Modenese, Luca and Phillips, Andrew TM and Jeffers, Jonathan RT},	64	author={van Arkel, Richard J and Modenese, Luca and Phillips, Andrew TM and Jeffers, Jonathan RT},
65	journal={Journal of Orthopaedic Research},	65	journal={Journal of Orthopaedic Research},
66	volume={31},	66	volume={31},
67	number={8},	67	number={8},
68	pages={1172--1179},	68	pages={1172--1179},
69	year={2013},	69	year={2013},
70	publisher={Wiley Online Library}	70	publisher={Wiley Online Library}
71	}	71	}
72	```	72	```
73		73
74	but a better example of use is provided in this other open access [paper](https://github.com/modenaxe/MuscleForceDirection/blob/master/doc/papers/Phillips%20et%20al.%20Inter%20Biomech%202015.pdf):	74	but a better example of use is provided in this other open access [paper](https://github.com/modenaxe/MuscleForceDirection/blob/master/doc/papers/Phillips%20et%20al.%20Inter%20Biomech%202015.pdf):
75		75
76	```bibtex	76	```bibtex
77	@article{phillips2015femoral,	77	@article{phillips2015femoral,
78	title={Femoral bone mesoscale structural architecture prediction using musculoskeletal and finite element modelling},	78	title={Femoral bone mesoscale structural architecture prediction using musculoskeletal and finite element modelling},
79	author={Phillips, Andrew TM and Villette, Claire C and Modenese, Luca},	79	author={Phillips, Andrew TM and Villette, Claire C and Modenese, Luca},
80	journal={International Biomechanics},	80	journal={International Biomechanics},
81	volume={2},	81	volume={2},
82	number={1},	82	number={1},
83	pages={43--61},	83	pages={43--61},
84	year={2015},	84	year={2015},
85	publisher={Taylor \& Francis}	85	publisher={Taylor \& Francis}
86	}	86	}
87	```	87	```
88		88
89	# How to contribute	89	# How to contribute
90		90
91	Feel free of contributing as by standard [GitHub	91	Feel free of contributing as by standard [GitHub
92	workflow](https://guides.github.com/activities/forking/):	92	workflow](https://guides.github.com/activities/forking/):
93		93
94	1. forking this repository	94	1. forking this repository
95	2. creating your own branch, where you make your modifications and improvements	95	2. creating your own branch, where you make your modifications and improvements
96	3. once you are happy with the new feature you have implemented create a pull	96	3. once you are happy with the new feature you have implemented create a pull
97	request	97	request
98		98
99	## Resources for learning how to contribute	99	## Resources for learning how to contribute
100	* If you want to contribute but you are not familiar with [Git](https://git-scm.com/), the [Software Carpentry Lessons](https://swcarpentry.github.io/git-novice/) are a perfect place to start with Git and GitHub.	100	* If you want to contribute but you are not familiar with [Git](https://git-scm.com/), the [Software Carpentry Lessons](https://swcarpentry.github.io/git-novice/) are a perfect place to start with Git and GitHub.
101	* If you know how to use git but you are not familiar with GitHub, you can check resources like ["First Contributions"](https://github.com/firstcontributions/first-contributions) to learn how to contribute to existing projects.	101	* If you know how to use git but you are not familiar with GitHub, you can check resources like ["First Contributions"](https://github.com/firstcontributions/first-contributions) to learn how to contribute to existing projects.
102		102
103	# Resource on combining finite element and musculoskeletal models	103	# Resource on combining finite element and musculoskeletal models
104	* OpenSim Webinar: ["Interfacing Musculoskeletal and Finite Element Models to Study Bone Structure & Adaptation"](https://www.youtube.com/watch?v=0e6vQV_ioCI)	104	* OpenSim Webinar: ["Interfacing Musculoskeletal and Finite Element Models to Study Bone Structure & Adaptation"](https://www.youtube.com/watch?v=0e6vQV_ioCI)
105		105
106	# Contributors	106	# Contributors
107	Several researchers have contributed to this package:	107	Several researchers have contributed to this package:
108	* [Luca Modenese](https://github.com/modenaxe): C++, Matlab	108	* [Luca Modenese](https://github.com/modenaxe): C++, Matlab
109	* [John J. Davis IV](https://github.com/johnjdavisiv): Plugin Matlab demo updated to OpenSim 4.2	109	* [John J. Davis IV](https://github.com/johnjdavisiv): Plugin Matlab demo updated to OpenSim 4.2
110	* [Ke Song](https://github.com/KSongGitHub): Matlab update to OpenSim 4.0	110	* [Ke Song](https://github.com/KSongGitHub): Matlab update to OpenSim 4.0
111	* [Dimitar Stanev](https://github.com/mitkof6): C++ update to OpenSim 4.0	111	* [Dimitar Stanev](https://github.com/mitkof6): C++ update to OpenSim 4.0
112	* [Claudio Pizzolato](https://github.com/cpizzolato): C++ makefiles	112	* [Claudio Pizzolato](https://github.com/cpizzolato): C++ makefiles
113	* [Friedl De Groote](https://github.com/FriedlDeGroote): C++ legacy [version](https://github.com/modenaxe/MuscleForceDirection/tree/master/CPP/legacy_code/OpenSim2.4_KULeuven) of v1.0	113	* [Friedl De Groote](https://github.com/FriedlDeGroote): C++ legacy [version](https://github.com/modenaxe/MuscleForceDirection/tree/master/CPP/legacy_code/OpenSim2.4_KULeuven) of v1.0
114	* Alfred Thibon: C++	114	* Alfred Thibon: C++