Muscle Wrapping 2.0¶

Muscle Wrapping 2.0 is a project that aims to develop [OpenSim](https://simtk.org/projects/opensim) compatible models and methods for wrapping the muscles, represented by their triangular surface models, around the moving bones and decomposing the output muscles into mechanical lines of action for consequent biomechanical analyses.

Overview¶

Project currently contains two main applications (OsimMuscleGeneratorTool, a plugin for OpenSim 4.0 software, and AttachmentEstimation, a tool for estimating the attachments of muscles on the bones), several examples and tests, and cadaver data for experimenting. The software architecture is schematically illustrated in the following figure.


Using OsimMuscleGeneratorTool¶

OsimMuscleGeneratorTool is a plugin for OpenSim 4.0. Taking an OpenSim musculoskeletal model and motion data as an input, it generates an arbitrary number of lines of action (fibres) composed of a user-defined number of straight-line segments for each skeletal muscle having known surface geometry and attachment areas. The outputs are the fibre lengths and moment arms for corresponding coordinates (changing according to the motion). Optionally, the plugin produces an OpenSim model in which the fibres are represented as actuators with predefined geometry paths.

The plugin is used from the command line as:

opensim-cmd.exe -L "OsimMuscleGeneratorTool.dll" run-tool setup_muscleGeneratorTool.xml

where setup_ muscleGeneratorTool.xml is the file containing the configuration of the plugin. Please make sure that the configuration, the plugin and all its dependencies are on path, or specify full paths (e.g., C:\Work\setup_muscleGeneratorTool.xml ).

The syntax of the plugin configuration file is visible in example present in Data folder. A short overview is also visible on [YouTube](https://www.youtube.com/watch?v=BW_jjCcbf5o).

Building from Sources¶

NOTE: On all platforms (Windows, Linux), you should build all dependencies with the
same CMAKE_BUILD_TYPE (Linux) / CONFIGURATION (MSVC) (e.g., Release, Debug) as Muscle Wrapping 2.0 applications. Failing to
do so may result in mysterious runtime errors.

Get the prerequisities¶

• C++ 11 or 17 compatible compiler/IDE: Visual Studio 2019 is recommended on Windows platforms, GCC 10.2 or CLANG 5.0 is recommended on Linux platforms; C++ 17 is required for AttachmentEstimation application.
• cross-platform build system:
  [CMake](http://www.cmake.org/cmake/resources/software.html) >= 3.10;
• Git version control: On Windows platforms, [Git for Windows](http://msysgit.github.io/) >=2.26 is required and [Git Extensions](http://gitextensions.github.io/) or [TortoiseGit](https://code.google.com/p/tortoisegit/wiki/Download) are recommended as tools for inexperienced users of Git;
• [OPTIONAL]: [Qt 5](https://doc.qt.io/qt-5/gettingstarted.html) - required only if you want to build (and use) MeshRegisterGUI example application

Building the critical dependencies¶

1) Get the source codes of the following dependencies:

• Visual ToolKit (VTK): [VTK](http://vtk.org) >= 8.2;
• VTK Visual Debugger: [vtkVisualDebugger](https://gitlab.com/besoft/vtkVisualDebugger).

2) Use CMake (cmake-gui is recommended for Windows users) to configure VTK.

NOTE:

• It is recommended to change ```CMAKE_INSTALL_PREFIX``` to directory where you would prefer to have the binaries of VTK. The default path (e.g., C:/Program Files (x86)/) is often not desirable.
• It is recommended to disable building shared libraries (```BUILD_SHARED_LIBS = OFF```) to make using MuscleWrapping 2.0 applications easier. When leaving this option ```ON```, either the path to the directory where the shared VTK libraries (e.g., vtkCommonCore-9.0.dll) reside (see ```CMAKE_INSTALL_PREFIX```) must be append to global paths, or the libraries must be coppied to the directory of the application.
• If you want to build (and use) MeshRegisterGUI application, you must set the option ```VTK_GROUP_ENABLE_Qt = YES```
  and specify the ```Qt5_DIR``` to the directory where you have the cmake config file for Qt 5 (Qt5-config.cmake), e.g., to C:/Qt/5.12.0/msvc2017_64/lib/cmake/Qt5.

3) Generate the project (Makefile on Linux). Open the project and build it.
IMPORTANT NOTE: There is a serious bug in VTK that has not been fixed yet. Please, patch manually Common/Math/vtkQuaternionInterpolator.cxx and Rendering/Core/vtkTransformInterpolator.cxx files as described in https://gitlab.kitware.com/vtk/vtk/-/merge_requests/5922/commits before building.

4) Once VTK is successfully built use CMake to install it.

NOTE: Using Visual Studio, you may install VTK by building the project named INSTALL.
5) Use CMake to configure VTK Visual Debugger.

NOTE:

• Set ```VTK_DIR``` to the directory containing vtk-config.cmake file. It should be inside the directory where you installed VTK (e.g., D:/VTK/Bin/Static_x64/lib/cmake/vtk-9.0).
• Once again, it is recommended to disable building shared libraries (see above).

7) Generate the project and built the code.

Building the OpenSim Core dependency
NOTE: OpenSim is required only if you want to build and use OsimMuscleGeneratorTool application, otherwise you may skip this step and proceed with the [building Muscle Wrapping 2.0 applications](#building-muscle-wrapping-20-applications).¶

Get the source code of [OpenSim 4.x Core](https://github.com/opensim-org/opensim-core) and
follow the instructions in readme.md to build and install OpenSim.

NOTE: On Windows platforms it is recommended to use superbuild to download and build OpenSim dependencies, in which case only the source codes of OpenSim and Git is needed. Furthermore, it is recommended to slightly modify the superbuild as follows:

• Only BTK, docopt, eigen, simbody, and spdlog dependencies are required, uncheck all other ```SUPERBUILD_``` options.
• When configuring opensim-core,
  1) specify MANUALLY ```OPENSIM_DEPENDENCIES_DIR``` because the path automatically provided by OpenSim CMakeList might be invalid. The correct path should be the directory specified for ```CMAKE_INSTALL_PREFIX``` when configuring opensim-core-dependencies.
  2) Uncheck ```OPENSIM_WITH_CASADI``` and ```OPENSIM_WITH_TROPTER``` options.

Building Muscle Wrapping 2.0 applications¶

Building Muscle Wrapping 2.0 applications is highly configurable using CMake. There are three options determining which applications should be built (and consequently also which internal dependencies) and which external dependencies will be required: ```BUILD_OSIM_APPLICATIONS```, ```BUILD_TEST_APPS```, and ```BUILD_KELLNHOFER_MULTIMORPHAPP```.

When none of these options are ```ON```, only the main applications requiring just the above described critical dependencies are built. Currently, this includes AttachmentEstimation application only. When ```BUILD_TEST_APPS``` is ```ON``` (it is ```OFF``` by default), all examples and test applications are built except for MeshRegisterGUI for which ```BUILD_KELLNHOFER_MULTIMORPHAPP``` must be also ```ON``` (default is ```OFF```). Please note that MeshRegisterGUI requires VTK with Qt5 support enabled. Setting ```BUILD_OSIM_APPLICATIONS = ON``` enables building of applications that requires OpenSim as an external dependency (see [Building the OpenSim Core dependency]) such as OsimMuscleGeneratorTool. We note that this option is ```ON``` by default.

Depending on the setting of above-mentioned options you may need to specify the following CMake variables:

• ```OpenSim_DIR``` must be set to the directory containing OpenSimConfig.cmake file (it should be in some subdirectory of the path where you installed OpenSim, e.g., C:/OpenSim/OpenSim4-install/cmake)
• ```vtkVisualDebugger_DIR``` should be set to the 'Where to build the binaries' directory of vtkVisualDebugger (e.g., C:/MuscleModelling/vtkVisualDebugger/build)

There are other options:

• ```USE_CXX_17``` Enables using C++ 17 standard even for the code that does not use features of C++ 17 (default is ```OFF```);
• ```ENABLE_OPENMP``` Enables multi-threading processing using OpenMP standard (default is ```ON```). While the processing is typically much faster when this option is ```ON```, it may complicate the debugging of the code.