Skip to content

Latest commit

 

History

History
124 lines (85 loc) · 8.17 KB

README.md

File metadata and controls

124 lines (85 loc) · 8.17 KB
Raw

Introduction

A Blender add-on for use in combination with the MyoGenerator add-on developed by Eva C. Herbst. It's purpose is to be able to easily export models of muscles with their origin and insertion areas out of Blender and decompose them into a set of muscle fibres - a more realistic representation.

It is supported by the Myogenerator add-on and Blender versions 2.8X.X - 2.9X.X

DOI for the newest release citations: DOI


A quick "Thank you"!

This add-on as basically a wrapper for an already existing muscle decompositor, which is a part of a bigger project called Muscle Wrapping 2.0 (if interested, please refer to HERE and HERE). I'd like to wholeheartedly thank all of it's creators (mainly Josef Kohout and Luca Modense). Thank you!

Installation

To install this add-on, download the intended released version HERE and proceed as follows: How to install. After a successfull installation, the add-on should be present on the right vertical add-on toolbar (showed by pressing the N key).

Model hierarchy

For the add-on to successfully decompose a muscle, the user has to create 3 separate models:

  • Model of the muscle volume
  • Model of the origin area
  • Model of the insertion area

The name of the models in the scene MUST follow a naming convention:

  • For the volume model:<muscle_name><space>volume
  • For the insertion area: <muscle_name><space>insertion<space>boundary
  • For the origin area: <muscle_name><space>origin<space>boundary

A proper muscle model could have following hierarchy (in the scene):

The name of the muscle model in this case is mAMEM_new

Add-on's quick overview

The add-on's GUI is fairly simple:

Output directory

This parameter is used for selecting a work folder. Export and decomposition functionallities are working with this directory.

Muscle name (decomposition)

This parameter serves only for the singular decomposition process (Decompose specified muscle(s)). After pressing this button, the add-on searches for the essential files in the current working directory (specified by Output directory)

Decomposition parameters

For the decomposition process, following parameters can be set, which implicate the model's structure:

  • Fibres: Number of muscle fibres of which the muscle should consist of
  • Resolution: Number of segments of each fiber (each fiber is basically a segmented line)
  • Visualization mode:
    • None - No visualization
    • Visualize - Standard visualization in a separate window
    • Debug For development purposes

Optional parameters

These parameters are not strictly required, though some of them are fairly recommended.

  • Vertices reordering (RECOMMENDED) - Reorder vertices into a sequential numbering order. It is strongly recommended for proper decomposition results.

  • Mesh triangulation - Convert quadrilateral volume meshes to a triangular one.

Exporting a model

The 3 separate models can be exported out of Blender. To export them, user has to select which of the model should be exported. (in the object hierarchy in the upper right corner; use CTRL + mouse click to select multiple parts) After that, click on the Export selected muscle(s) to export all the selected models (and their parts). The number of models/parts to export is not limited.

If the export was successfull, the following pop-up should appear:

If a dialog with different a message appears, please proceed to the Troubleshooting section

and a new file, in the working directory, should appear (with the same name).

The export format is VTK for the insertion/origin areas, STL for the volume.

Decomposing a model

If a user already has the model parts as files on the disk, the exporting process can be skipped. For the model decomposition, the files (representing each model(s) part(s)) MUST BE present in the current working directory. After that, a user has 2 decomposition options:

  • Decompose specified muscle: To decompose only a single muscle, user has to specify a name of the muscle (only the name). This is partly why the naming conventions need to be complied with.
  • Decompose all muscles: The current working folder is searched through, extracting every unique muscle name and decomposing all muscles found.

IMPORTANT! Make sure you set the decomposition parameters BEFORE clicking on one of the decompose buttons. If you want to change the already decomposed model's parameters, you need to set new ones and press the decompose button again.

After click either of the buttons, the model is imported automatically back into Blender, if the process finished successfully. Also, a decomposed model source file is created in the current working folder

If not, the model is not imported into Blender and one of the possible error pop-ups appears. If that's the case, please proceed to the Troubleshooting section.

Troubleshooting

During using the add-on, you might run into a few warnings/errors. Below, there's an available list suggesting a simple troubleshooting:

  • No object(s) selected!: You have tried to export a muscle (or its part), but you have not selected the model. Make sure the proper object is selected.

  • Wrong muscle name format! Model should...: When exporting, make sure the model is named compliant to the naming conventions.

  • File was not found! Please, check the filename and directory. (File: ...): This error mostly happens, when a user chose a working directory, but the file is not present. These pop-ups should always contain a path to the file, which was not found, so make sure to check if the path is right and if the file is in the correct folder.

  • No muscles to decompose found in the specified directory: Current working directory is most likely empty. Make sure, you're in the right tdirectory. If it is not empty, make sure you're following the naming conventions

  • MuscleDecomposition executable has not been found ...: For decomposition, there's an essential tool in the add-on's source files. Open your file explorer and navigate to your Blender's add-on's folder (default: %appdata%\Blender Foundation\Blender<version>\scripts\addons\Myogenerator_Exporter\Assets).

    In this folder, there should be a file named MuscleDecompositionTest (.exe for Windows platform). Most likely, it is missing. This issue should be easily fixable by reinstalling the add-on, or download the executable from the source files (Windows only build) and copy it into the mentioned folder.

    Unfortunately, there's not a version for Linux, for now. If you're interested, please let me know and I might be able to create a version for other OS, if there's enough interest.

  • Decomposition has been aborted due to the following reason:: Something went wrong during the decomposition process. Try to decompose a muscle with visualization mode = 2, screenshot the console output and open an issue on the GitHub repository.

If you have run into other errors, please feel free to open an issue on the official GitHub repository :-).