Bender/Documentation/2.0/Modules/FEMWorkflow: Difference between revisions

From KitwarePublic
Jump to navigationJump to search
 
(146 intermediate revisions by 2 users not shown)
Line 1: Line 1:
= Introduction =
= Introduction =
This module guides the user step-by-step into transforming a volume using a rigging, skinning and posing technique.
The [[../FEMWorkflow|Workflow]] module guides the user step-by-step into transforming a volume using a [http://en.wikipedia.org/wiki/Skeletal_animation rigging, skinning and posing] technique using a multimaterial tetrahedral mesh and Finite Element Method (FEM).
 
Typically, the anatomical pose of a voxelized model is limited by the imaging device used to acquire the underlying data, e.g., MRI and CT scanners have narrow entries. Changing the pose of an already acquired voxelized anatomical model enables new processing of human anatomy in a wide variety of poses. The workflow module allows an operator to specify a rigging that represents the anatomical pose of an existing voxel model, manipulate that rigging into a different anatomical pose, and then generate a new voxelized model that represents the original model resampled into that new position.
 
This module applies to voxelized models the [http://en.wikipedia.org/wiki/Skeletal_animation Skeletal animation] technique initially conceived for surfaces.  


= Details =  
= Details =  
Line 9: Line 13:


= Use Cases =
= Use Cases =
<gallery widths=220px perrow=5>
Image:BenderFEMWorkflow-v2.0-1-LoadInputs.png|[[#1.29_Adjust_labelmap |1) Load Inputs]]
Image:BenderFEMWorkflow-v2.0-2A-MergeLabels.png|[[#A.29_Merge_labels |2-A) Merge labels]]
Image:BenderFEMWorkflow-v2.0-2B-ResampleAndPad.png|[[#B.29_Resample_image |2-B) and 2-C) Voting Resample and Pad Image]]
Image:BenderFEMWorkflow-v2.0-3A-CreateTetMesh.png|[[#A.29_Create_tetrahedral_mesh |3-A) Create tetrahedral mesh]]
Image:BenderFEMWorkflow-v2.0-3B-ExtractBoneMesh.png|[[#B.29_Extract_bone_mesh |3-B) Extract bone mesh]]
Image:BenderFEMWorkflow-v2.0-3C-ExtractSkinMesh.png|[[#C.29_Extract_skin_mesh |3-C) Extract skin mesh]]
Image:BenderFEMWorkflow-v2.0-4-Armatures.png|[[#4.29_Create_armature_.28rigging.29 |4) Armature/Rig]]
Image:BenderFEMWorkflow-v2.0-5-VolumeSkinning.png|[[#5.29_Volume_skinning |5) Volume skinning]]
Image:BenderFEMWorkflow-v2.0-6-ComputeWeights.png|[[#6.29_Compute_weights |6) Bone weights]]
Image:BenderFEMWorkflow-v2.0-7-SimulatePose.png|[[#7.29_Pose_armature_.28posing.29 |7) Pose surface]]
</gallery>
<!--
<gallery>
<gallery>
Image:Workflow-Page1-1.0.png|2mm labelmap volume loaded in workflow
Image:Workflow-Page1-1.0.png|2mm labelmap volume loaded in workflow
Image:Workflow-Page2-1.0.png|Bone and Skin surfaces extracted from 2mm labelmap volume
Image:Workflow-Page2-1.0.png|Bone and skin surfaces extracted from 2mm labelmap volume
Image:Workflow-Page3-1.0.png|Rigging
Image:Workflow-Page3-1.0.png|Rigging
Image:Workflow-Page4-1.0.png|Volume Skinning
Image:Workflow-Page4-1.0.png|Volume skinning
Image:Workflow-Page5-1.0.png|Pose surface with bone model
Image:Workflow-Page6-1.0.png|Pose labelmap
</gallery>
</gallery>
-->
= Tutorials =
{|
|[[Image:Bender-2.0-tutorial-video.png|link=http://vimeo.com/73247670|400px|thumb|[[Bender/Documentation/2.0/Tutorial|Arm tutorial]]]]
|}


= Parameters =
= Parameters =
== Advanced properties==
== Advanced properties==
The [[#Advanced_properties|Advanced properties]] can be shown or hidden by clicking on the [[Image:BenderExpandIcon.png]] expanding button.
===Settings===
{| width="100%"
|valign="top"|
*'''Workflow mode''': Show/Hide advanced controls at each step of the workflow. There are 3 modes
** '''Basic''': Most of the parameters are hidden, it provides a very simple step by step workflow.
** '''Intermediate''': The main parameters are visible, the advanced options are hidden. In this mode, it is possible to go to the next step even without finishing the current step. It can be useful when starting a workflow not from scratch.
** '''Advanced''': Full control is given to the user, almost all the parameters are shown. The full list of parameters is available in the specific module panels that can be opened by clicking the "Go to XYZ" buttons.
* '''Reload module''': If the module script is edited, clicking the button reloads the script. It can be used to tweak the behavior of the module. 
|valign="top"|[[Image:AdvancedPanel-Settings-1.1.png|thumb|550px|Settings panel]]
|}
===Data===
{| width="100%"
|valign="top"|
* '''Visible''': Check/Uncheck the data (Volume or Surface model) to show/hide in the 2D and/or 3D views.
|valign="top"|[[Image:FEMWorkflow-AdvancedPanel-Data-1.1.png|thumb|550px|Data panel]]
|}
===Volume Rendering===
{| width="100%"
{| width="100%"
|valign="top"|
|valign="top"|
*'''Advanced Workflow''': Show/Hide advanced controls at each step of the workflow.
The [[#Volume_Rendering|Volume Rendering]] section can volume render intermediate or final volume/labelmap.
*:Advanced properties are automatically set by the workflow logic for a "standard" processing. Nonetheless it is possible for the user to tweak those parameters.
 
*:Note that all the parameters are not exposed even in "Advanced Workflow" mode. The full list of parameters is available in the specific module panels that can be opened by clicking the "Go to XYZ" buttons.  
===Volume Render===
* '''Labelmap''': Select the volume/labelmap you want to volume render. The checkbox next to labelmap controls whether the rendering is visible or not.
* '''Labelmap''': Select the volume/labelmap you want to volume render. The checkbox next to labelmap controls whether the rendering is visible or not.
* '''Label(s)''': List all the label(s) that should be visible (i.e. opacity > 0.), all the other labels will be hidden (i.e. opacity = 0.). Labels must be separated with a ',' (comma).
* '''Label(s)''': List all the label(s) that should be visible (i.e. opacity > 0.), all the other labels will be hidden (i.e. opacity = 0.). Labels must be separated with a ',' (comma).
* '''Crop''': Show/Hide a cropping box to apply to the volume rendering. Any voxel outside the box will be hidden.
* '''Go To Volume Rendering''': Opens the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/VolumeRendering Volume Rendering] module. It gives full control over the volume rendering parameters such as the color and opacity transfer functions, shading, rendering quality...
* '''Go To Volume Rendering''': Opens the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/VolumeRendering Volume Rendering] module. It gives full control over the volume rendering parameters such as the color and opacity transfer functions, shading, rendering quality...
|[[Image:AdvancedPanel-1.0.png|thumb|550px|Advanced properties panel]]
|valign="top"|[[Image:FEMWorkflow-AdvancedPanel-VolumeRendering-2.0.png|thumb|550px|Volume Rendering panel]]
|}
|}


== 1) Adjust Labelmap ==
== 1) Adjust labelmap ==
 
The [[#1.29_Adjust_labelmap|Adjust labelmap]] is the first step of the workflow. The user selects here the volume to pose and can optionally prepare the volume before any further computation is applied.
 
{| width="100%"
{| width="100%"
| valign="top"|
| valign="top"|
===A) Labelmap===
===A) Labelmap===


'''Simple workflow'''
This section makes sure the input labelmap has the right color table associated with it and is in the right coordinate system.
* '''Volume''': Select the volume/labelmap that you want to reposition. Read [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/SlicerApplication/LoadingData here] the instructions to load data into Bender.  
 
* '''Colors''': Select the color transfer function to apply to the volume . It will The transfer function is used to  
'''Simple options'''
* '''Apply''': Set the color transfer function to the volume.
* '''Volume''': Select the volume/labelmap that you want to reposition. Read [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/SlicerApplication/LoadingData here] the instructions to load data into Bender. The choosen volume will be automatically set as the default volume for all the following steps.
* '''LPS<->RAS''': Apply a (-1,-1, 1) transform to the volume. It can be used to apply the same coordinate system used by Bender to the volume. The "R,L,A,P,S,I" letters on the purple box in the 3D view represent the orientations "Right, Left, Anterior, Posterior, Superior, Inferior".
* '''Colors''': Select the color transfer function to apply to the volume. It is assigned to the volume automatically once selected. For each voxel intensity, a unique color is associated and is used at display time. It is important to select the right transfer function of the volume because the color names in the color transfer function are used in the [[#B.29_Merge_labels|Merge labels]] section. ''Grayscale'' means the volume is not a labelmap and there is no color transfer function associated to it.
'''Advanced workflow'''
'''Advanced options'''
* '''Go To Volumes''': Go to the [http://www.slicer.org/slicerWiki/index.php?title=Documentation/4.1/Modules/Volumes Volumes] module to read volume information (such as its size, origin, spacing, scalar type, range...) and display properties (window/level, threshold, interpolation...)
* '''Go to Volumes module''': Go to the [http://www.slicer.org/slicerWiki/index.php?title=Documentation/4.1/Modules/Volumes Volumes] module to read volume information (such as its size, origin, spacing, scalar type, range...) and display properties (window/level, threshold, interpolation...)
* '''Go to Label Statistics module''': Go to the [[../LabelStatistics|Label Statistics]] module to compute statistics for each label of the loaded labelmap.
* '''LPS <-> RAS''': Apply a (-1,-1, 1) transform to the volume. It can be used to apply the same coordinate system used by Bender to the volume. The "R,L,A,P,S,I" letters on the purple box in the 3D view represent the orientations "Right, Left, Anterior, Posterior, Superior, Inferior". Other transforms are available as well when opening the button's menu:
** '''Posterior <-> Anterior''' flips the image around the posterior anterior plane.
** '''Superior <-> Inferior''' flips the image around the superior/inferior plane.
** '''Center''' translates the image to the origin.
 
|valign="top"|[[Image:BenderFEMWorkflowAdjustPanel-2.0.png|thumb|550px|Adjust labelmap panel]]
|}
 
== 2) Merge and resample ==
 
The [[#2.29_Extract_bone_and_skin|2) Extract bone and skin]] page creates the bone and skin surface models to interactively control the posing.
 
{| width="100%"
| valign="top"|
===A) Merge labels===
 
Some labelmaps can have multiple labels for representing bones (e.g. bone marrow, bone cancellous, skull...). This section provides the functionality of merging the bones labels and the skin labels of the input labelmap to simplify the visualization and usability of the bones and the skin.
It is important to merge those similar labels into a unique label (1 for the bones, 1 for the skin) as the Bender workflow handles only 1 label for the bones and 1 label for the skin. .
 
'''Simple options'''
* '''Output Labelmap''': Select the output labelmap that will contain all the labels of the input labelmap and the merged labels.
* '''Merge Labels''': Merge all the '''Input Labelmap''' labels into their corresponding labels given by '''the table'''.
'''Advanced options'''
* '''Input Labelmap''': Select the input labelmap that needs labels to be merged together. By default, it is ''Volume'' in [[#A.29_Labelmap|A) Labelmap]].
* '''The table''': The table lists all the labels that will be merged in one of the label categories. The different possible label categories are listed on the left side of the table. These labels corresponds from top to bottom to:
**Background
**Bone
**Muscle
**Skin
One the right side of each of those labels is listed all the labels that will be changed into one of them. These labels are automatically selected from the input volume color table (set in [[#A.29_Labelmap|A) Labelmap]]) by looking for color names containing the strings corresponding strings.
* '''Go To Change Label''': Open the [[../ChangeLabel|Change Label]] module to merge other labels together or simply change label values.
 
===B) Resample image ===
 
This section resamples the input merged labelmap using the [[../VotingResample| Voting Resample]] module. This allow the mesh computation in [[#A.29_Create_tetrahedral_mesh| Create Tetrahedral Mesh]] to be faster and lighter. The [[../VotingResample| Voting Resample]] module is used here to make that the '''Bone''' and '''Skin''' and '''Muscle''' are not resampled in place of the background.
 
'''Simple options'''
* '''Output labelmap''': Select the output labelmap under which the resampled image will be stored.
* '''Scale factor''': Precise here the scale factor by which the '''Input Labelmap''' will be resampled down. The higher the factor is, the faster subsequent computation on the mesh will be. However this implies a loss of details which can lead to a mesh poorly representing the original data.
* '''Resample''': Using a voting scheme and the '''High''' and '''Low precedence labels''', downsample the '''Input labelmap'''.
'''Advanced options'''
* '''Input labelmap''': Select the labelmap to resample from.
* '''High precedence labels''': When downsampling an image, the algorithm must choose between labels to pick from for the new image. '''High precendence labels''' are always picked over the other labels. Order matters here as the first '''High precendence label''' is the label with the most precedence. In the workflow case, the precedence order is always '''Skin''', '''Bone''' and '''Muscle'''. This allows us to make sure that the resampling does not change any of the image data to background.
* '''Low precedence labels''': Much like the '''High precendence labels''', '''Low precendence labels''' help to decide what label is picked over which when resampling. '''Low precendence labels''' are never picked over the other labels. Order matters here as the first '''Low precendence label''' is the label with the least precedence. In the workflow case, the '''background''' is used.
 
* '''Go To Voting Resample''': Open the [[../VotingResample|Voting Resample]] module to access more controls over the resampling.


===B) Merge labels===
===C) Pad Image===


This section simply pads the resample image of a few voxels to prepare it for the mesh generation using the [[../PadImage|Pad Image]] module.


'''Simple workflow'''
'''Simple options'''
* '''Output Labelmap''': Select the labelmap for which the labels will be merged together.
* '''Output labelmap''': Select the output for padded labelmap.
* '''Merge labels''': Merge the '''Bone Label(s)''' and '''Skin Label(s)''' from '''Input Labelmap''' (into respectively '''Bone Label''' and '''Skin Label''') and outputs the result in '''Output Labelmap'''. This allows to extract or visualize the '''Bone Model''' and the '''Skin Model''' (see ''2) Extract Bone and Skin'') more easily.
* '''Pad thickness''': Select the number of voxels of padding added around the '''Input labelmap'''. Two voxels is enough for the [[../CreateTetrahedralMesh|Create Tetrahedral Mesh]] module. More voxels can slow down the computation.
* '''Pad''': Add extra padding voxels around the '''Input labelmap'''.
'''Advanced workflow'''
'''Advanced workflow'''
* '''Input Labelmap''': Select the labelmap that needs label to be merge together. Set by default to the selected volume in '''A) Labelmap'''.
* '''Input labelmap''': Select the labelmap volume to add voxels to.
* '''Bone label(s)''': Choose the label(s) that will be merge into the '''Bone Label'''. They are automatically computed based on the input volume color table by looking for names containing "bone" and "vertebrae" in it.
* '''Pad value''': Set the value of the voxels added to the '''Input labelmap'''. In this case, the value added is the '''background''' label.
* '''Bone label''': Select the new label value of the '''Bone Label(s)'''.
* '''Go To Pad Image Module''': Open the [[../PadImage|Pad Image]] module.  
* '''Skin label(s)''': Choose the label(s) that will be merge into the '''Skin Label'''. They are automatically computed based on the input volume color table by looking for names containing "skin" in it.
* '''Bone label''': Select the new label value of the '''Skin Label(s)'''.
* '''Go To Change Label''': Opens the Change Label CLI.


|[[Image:AdjustPanel-1.0.png|thumb|550px|Adjust labelmap panel]]
| valign="top"|
[[Image:BenderFEMExtractModelsPanel-2.0.png|thumb|550px|Extract bone and skin panel]]
[[Image:BenderFEMWorkflow-2A-MergeLabels-2.0.png|thumb|550px|2-A)Merge labels]]
[[Image:BenderFEMWorkflow-2B-ResampleImage-2.0.png|thumb|550px|2-B) and 2-C)Resample image and Pad image]]
|}
|}


== 2) Extract Bone and Skin ==
== 3) Extract materials ==
 
The [[#3.29_Extract_materials|3) Extract materials]] page generates a multi-material tetrahedral mesh from the image and extracts bone and skin surface models to interactively control the posing.
 
{| width="100%"
{| width="100%"
| valign="top"|
| valign="top"|
===A) Create tetrahedral mesh===
In a FEM workflow, repositioning happens on a tetrahedral mesh instead of a labelmap volume. This section generates tetrahedrals with associated material for each voxel.
'''Simple options'''
* '''Output Mesh''': Select the output that will contain the tetrahedral mesh.
'''Advanced options'''
* '''Merged labelmap''': Select the input labelmap that contains a limited number of materials (up to 3). By default, it is ''Output labelmap'' in [[#C.29_Pad_image|2.C) Pad image]].
* '''Pad image''': If non zero labels are at the border of the image, pad the image for correct results. This option is not required if the image has previously been padded in [[#C.29_Pad_image|2.C) Pad image]].
* '''Go To Create Tetrahedral Mesh module''': Open the [[../CreateTetrahedralMesh|Create Tetrahedral Mesh]] module to generate the tetrahedral mesh.
===B) Extract bone mesh ===
This section extracts the bone material from the input tetrahedral mesh.
'''Simple options'''
* '''Output bone mesh''': Select the output mesh where the result mesh will be stored.
* '''Extract bone model''': Generate the bone model using the [[../VolumeMaterialExtractor|Volume Material Extractor]] module. The extracted bone mesh is used when placing or adjusting the armature by ensuring the armature bones are on top of the labelmap bones.
'''Advanced options'''
* '''Input mesh''': Select the tetrahedral mesh to extract the bone label from.
* '''Bone material''': Select the label in the input mesh to create the bone mesh from. By default, it is the '''Bone Label''' value in [[#A.29_Merge_labels|Merge labels]].
* '''Go To Volume Material Extractor module''': Open the [[../VolumeMaterialExtractor|Volume Material Extractor]] module to access more controls over the model extraction parameters.
===C) Extract skin mesh===


===A) Bone Model Maker ===
This section extracts the surface of the skin label in the input labelmap volume. The algorithm is different than [[#B.29_Extract_bone_mesh|Extract bone mesh]] because it solely needs the information of the background label. It creates an outer surface of the Foreground labels (all the labels that are not "Background").  
'''Simple workflow'''
* '''Output model hierarchy''': Select the output model hierarchy under which the bone model will be stored.
* '''Generate bone model''': Using the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/MergeModels Model Maker], generate the bone model. The bone model will be used when placing the armature. It allows to place the armature bones on top the real bones for a better and more natural posing.
'''Advanced workflow'''
* '''Label(s)''': Select the label that will be used to create the bone model. By default, it automatically uses the label from '''Bone Label''' (in ''1) A)'').
* '''Go To Models''': Opens the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/Models Models] module.
* '''Go To Model Maker''': Opens the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/MergeModels Models] module.


===B) Skin model maker===
'''Simple options'''
'''Simple workflow'''
* '''Output skin model''': Select the output model for the skin model.
* '''Output''': Select the output model for the skin model.
* '''Show/Hide skin''': Toggle the visibility of the generated model in '''Output skin model'''.
* '''Toggle skin visibility''': Toggle the visibility of the model selected in '''Output'''.
* '''Extract skin mesh''': Using the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/GrayscaleModelMaker Grayscale Model Maker], extract the outer surface of the '''Input Labelmap'''. The skin surface is used to enable collision when reposing the entire tetrahedral mesh in [[#7.29_Pose_armature_.28posing.29|7) Pose Armature(posing)]].  
* '''Generate skin model''': Using the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/GrayscaleModelMaker Grayscale Model Maker], extract the outer surface of the '''Input Labelmap'''. The skin model can be used to help find the right pose with no overlaps by using the ''5) Pose Armature(posing)''.  
'''Advanced options'''
'''Advanced workflow'''
* '''Input labelmap''': Select the labelmap volume to extract the skin model from.
* '''Input Labelmap''': Select the labelmap that will be used to create the skin model.
* '''Background label''': Select the threshold used to differentiate the body in the labelmap (foreground) from the outside air (background). Default is 0.
* '''Threshold''': Select the threshold that will be used to differentiate the body in the labelmap from the outside (usually air). Default is 0.1.
* '''Use skin label''': Peel the skin from the input labelmap, this generates an eroded skin model.
* '''Go To Models''': Opens the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/Models Models] module.
* '''Skin label''': Value of the skin label
* '''Go To Grayscale Model Maker''':Opens the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/GrayscaleModelMaker Grayscale Model Maker] module.
* '''Output spacing''': Controls the spacing of the points in the generated decimated mesh.
* '''Smooth''': Apply smoothing filter on the generated surface mesh. A smooth surface improves the collision detection at the [[#7.29_Simulate_Pose|7) Simulate Pose]] step.
* '''Go To Models''': Open the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/Models Models] module to change the created model properties such as name, opacity, color...
* '''Go To Skin Model Maker''': Open the [[../SkinModelMaker|Skin Model Maker]] module to access more controls over the model extraction parameters such as smoothing.  


| align="right"|
| valign="top"|
[[Image:ExtractModelsPanel-1.0.png|thumb|550px|Extract bone and skin panel]]
[[Image:BenderFEM-ExtractMaterialsPanel-2.0.png|thumb|550px|Extract materials panel]]
[[Image:BenderFEMWorkflow-3A-CreateTetrahedralMesh-2.0.png|thumb|550px|3-A)Create tetrahedral mesh]]
[[Image:BenderFEMWorkflow-3B-ExtractBoneMesh-2.0.png|thumb|550px|3-B)Extract bone mesh]]
[[Image:BenderFEMWorkflow-3C-ExtractSkinMesh-2.0.png|thumb|550px|3-C)Extract skin mesh]]
|}
|}


== 3) Create armature (rigging) ==
== 4) Create armature (rigging) ==
 
This section creates the rig of the volume to pose.
'''Note:''' When opening this page, the view will automatically switch to ''3D Only'' to help creating/visualizing the armature.
 
{| width="100%"
{| width="100%"
| valign="top"|
| valign="top"|
===A) Armatures ===
===A) Armatures ===


When opening this page, the view will automatically switch to ''3D Only''.
Manually create or load an existing armature to fit on the bones of the volume to pose. The user is redirected to the [[../Armatures|Armatures]] module for manually editing (e.g. create/edit/remove a bone segment).
The armature (either created or loaded) is the interface between the user and the transformations needed to pose the volume models.
'''Note:''' Once completed, the armature rest positions should not be changed since it would require all the following computations to be updated as well. It is therefore highly encouraged to save the created armature in order to be able to restore it with '''Load armature from model'''.


'''Simple workflow'''
'''Simple workflow'''
* '''Toggle Skin visibility''': Does the same as '''Toggle Skin Visibility''' in ''2) B)''. It is advised to turn off the skin visibility so when placing bone, they automatically will drop at the same depth as the skeleton model instead of the skin model.
* '''Select a Preset''': Choose a preset armature to load in the workflow. The preset armature are the same available than in the [[../Armatures|Armatures]] module. Which armature to load can be chosen by expanding the button's menu. This also allows to open directly an armature from file by clicking the option '''Load armature from file'''.
* '''Load armature from model''': Prompts a dialog window to open an armature from a model. See [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/Armatures Armature Module] for further details.
* '''Toggle Skin visibility''': Same as '''Toggle Skin Visibility''' in [[#B.29_Skin_model_maker|Skin model maker]]. When dropping bones, bones are placed in 3D where the user click (X,Y) and at the depth (Z) of the closest surface model under the mouse cursor. It is advised to hide skin model when placing armature bones because you want them on the bones surface and not the skin surface .
* '''Go To Armature Module''': Opens the [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/Armatures Armature Module].
* '''Load armature from model''': Open a dialog window to load an armature from a model file. See [[../Armatures|Armatures]] module for further details.
* '''Go To Armature Module''': Open the [[../Armatures|Armatures]] module to manually edit the armature by adding, moving, deleting bones in Rest mode. Armature display properties such as X-Ray mode, opacity, color or shape can also be modified.
 
| valign="top"|
[[Image:BenderFEMWorkflow-ArmaturesPanels.png||thumb|550px|4) Armature/Rig]][[Image:BenderFEMWorkflow-v2.0-4-Armatures.png|thumb|550px|4)Armatures]]
|}
 
== 5) Volume skinning ==


The armature (either created or loaded) is the interface between the user and the transformations needed to pose the volume models. Once completed, the armature rest positions should not be changed since it would necessitate all the following computation to be updated as well. It is therefore highly encouraged to save the created armature in order to be able to restore it with '''Load armature from model'''.
Before computing the weights, the skinning volume must first be extracted. The skinning volume represents what bone influence the most a given voxel. For each voxel a unique bone index is assigned.
This means that if we were to use binary weights (see [[../ComputeArmatureWeight|Compute Armature Weight]]), a given voxel would rotate similarly to its associated bone in the skinned volume. Because the skinning might not produces perfect results (some voxels might be assigned the wrong bones), and because the skinned volume drives the weight computation, it can be useful to tweak the output skinned volume, most notably in joints area. The [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.3/Modules/Editor Editor] module can be used to edit the labelmap.


| align="right"|
'''Note:''' When opening this page, the view switches to ''Four Up''.
[[Image:RigArmaturePanel-1.0.png|thumb|550px|Rig armature panel]]
|}


== 4) Compute weights (skinning) ==
{| width="100%"
{| width="100%"
| valign="top"|
| valign="top"|


When opening this page, the view will automatically switch to ''Four Up''.
===A) Volume skinning===


===A) Volume Skinning===
'''Simple workflow'''
'''Simple workflow'''
* '''Volume''': Select the volume/labelmap that will be used for the skinning.
* '''Skin volume''': Compute the skinned volume. The output skinned volume is a labelmap where each voxel of the input '''Volume''' is associated with a bone of the input '''Armature''' (voronoi style algorithm).
* '''Armature''': Select the armature associated with the '''Volume'''.
 
* '''Output skinned volume''': Select the output volume.
* '''Skin volume''': Compute the skinned volume. The output skinned volume is a labelmap where each voxel of the input '''Volume''' is associated with a bone of the input '''Armature'''.
'''Advanced workflow'''
'''Advanced workflow'''
* '''Go To Volume Skinning Module''': Opens the [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/VolumeSkinning Volume Skinning] module.
* '''Volume''': Select the labelmap volume to use for skinning.
* '''Armature''': Select the armature to skin '''Volume'''.
* '''Output skinned volume''': Select the volume that will contain the output skinned volume.
* '''Go To Volume Skinning Module''': Open the [[../VolumeSkinning|Volume Skinning]] module for advanced properties.
 
===B) Edit volume skinning===


===A) Compute Armature Weight===
'''Simple workflow'''
'''Simple workflow'''
* '''Output weight image folder''': Select the folder where the weight images will be saved.
* '''Go To Editor Module''': Open the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.3/Modules/Editor Editor] module with the skinned volume obtained by the [[#A) Volume skinning| volume skinning]].
* '''Compute weights''': Compute the weight image. For each bone of the '''Armature''' a weight image is created. A weight image stores by how much a given voxel of the '''Volume''' will be influenced when the associated bone moves.
 
'''Advanced workflow'''
'''Advanced workflow'''
* '''Volume''': Select the volume/labelmap that will be used for the weight computation. It should be the that was used for the ''A) Volume Skinning''.
* '''Skinned volume''': Select the volume that will be modified in the editor. More information in the [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.3/Modules/Editor Editor] module documentation.
* '''Armature''': Select the armature associated with the '''Volume'''. It should be the that was used for the ''A) Volume Skinning''.
* '''Input skinned volume''': Select the skinned volume. It should be the (possibly tweaked) volume associated with the '''Volume''' and the '''Armature'''.
* '''Go To Compute Armature Weights Module''': Opens the [http://public.kitware.com/Wiki/Bender/Documentation/1.0/Modules/ComputeArmatureWeight Compute Armature Weight] module.


| align="right"|
| valign="top"|
[[Image:SkinArmaturePanel-1.0.png|thumb|550px|Skin volume panel]]
[[Image:BenderFEMWorkflow-5-VolumeSkinning-2.0.png|thumb|550px|Skin volume panel]]
[[Image:BenderWorkflow-v1.1-4-VolumeSkinning.png|thumb|550px|4)Volume skinning]]
|}
|}


== 5) Pose armature (posing)==
== 6) Compute weights  ==
The [[#6.29_Compute_weights|Compute weights]] section assigns a weight for each voxel of the input volume. The weights represent how much a voxel is influenced by a bone. It is later used when posing the volume and computing the unique transform to apply at a voxel (by interpolating the influencing bones transforms).
 
{| width="100%"
{| width="100%"
| valign="top"|
| valign="top"|


When opening this page, the current armature (if any) will automatically switch to ''Pose'' mode.
=== A) Compute armature weight ===
 
Smooth the Skinned volume by computing weights in order to consider the influence of every bone on a given voxel.


===A) Evaluate Surface Weight===
'''Simple workflow'''
'''Simple workflow'''
* '''Output surface''': Select the output surface with the weight evaluated for each of its points.
* '''Output weight image folder''': Select the folder where the weight images will be saved. You need to have user write access.
* '''Evaluate surface weight''': For each point of the '''Input Surface''', evaluates of the influence of all weight and add it as a field array. This will improve the computationnal time of the '''Pose Surface'''.
* '''Compute weights''': Compute the weight images. For each bone of the '''Armature''', a weight image is created. A weight image stores by how much a given voxel of the '''Volume''' will be influenced when the associated bone moves. This computation is done by solving a heat-diffusion equation in which the bones of the volume represent the hot source. To increase computation speed, the input images are first downsampled by a scale factor. The resulting weight image is then upsampled back to the original image spacing.
 
'''Advanced workflow'''
'''Advanced workflow'''
* '''Input surface''': Select the input surface that will have the weight evaluated on.
* '''Volume''': Select the volume that will be used for weight computation. It should be the same as in [[#A.29_Volume_skinning|A) Volume Skinning]].
* '''Weight images folder''': Select the folder where the weight images are.
* '''Armature''': Select the armature associated with '''Volume'''. It should be the same as in [[#A.29_Volume_skinning|A) Volume Skinning]].
* '''Go To Evaluate Surface Weight Module''': Opens the [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/EvalWeight Evaluate Weight] module.
* '''Input skinned volume''': Select the skinned volume to use for its bone regions. It should be the (possibly edited) volume associated with the '''Volume''' and the '''Armature''' generated in [[#A.29_Volume_skinning|A) Volume Skinning]].
* '''Background label''': Treat the given pixel value as backgroung. It will not be part of the weight computation.
* '''Bone label''': The bone label represents all the points of the labelmap which movement completely depend on one and only one bone of the armature. In the weights image, these points will either have the value 1 or 0 depending on their distance to the closest armature bone. In an anatomical study, this label should correspond to the bones of the patient. By default, the value is the same as the value used to [[#B) Bone model maker |extract the bones surface]].
* '''Padding''': Defines how far (in voxel units) outside the body the weight region will be computed. This can be useful in certain case where one wants to pose a surface that doesn't exactly lies on the body (for example, the skin obtained with a simple [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/GrayscaleModelMaker grayscale Model Maker]). However, padding can cause issue around joints (most notably the armpits) and isn't necessary when posing a labelmap.
* '''Scale factor''': The scale factor is used to speed up the processing. The weights are computated on downsampled version of the input labelmap according to this factor. These images are then up-sampled back to make sure they match the input image well. With a big scale factor, the computation will be faster but the weight images will be coarser.
* '''Go To Compute Armature Weights module''': Open the [[../ComputeArmatureWeight|Compute Armature Weight]] module to further refine the computation of the weights by, for example, restricting it to a given bone or changing the downsampling ratio.
 
=== B) Evaluate weights ===
 
Evaluate weights at each vertices of the tetrahedral mesh.


===A) Armatures===
'''Simple workflow'''
'''Simple workflow'''
* '''Go Armature Module''': Opens the [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/Armatures Armature] module.
* '''Output mesh''': Select the output surface that will contain the evaluated weights at each point of '''Input surface'''.
* '''Evaluate weights''': For each point of the '''Input Surface''', evaluate the influence (weight) of each bone and add the weights into field arrays (one point data array per bone). This improves the computational time of the '''Pose Surface'''.
'''Advanced workflow'''
* '''Input mesh''': Select the input surface that will have the weight evaluated on.
* '''Weight images folder''': Select the folder containing the weight image files.
* '''Go To Evaluate Surface Weight module''': Open the [[../EvalWeight|Evaluate weights]] module to access further parameters.
 
=== C) Material properties ===
 
Apply material properties at each vertices of the tetrahedral mesh.


===A) Pose Surface===
'''Simple workflow'''
'''Simple workflow'''
* '''Output surface''': Select the output surface that will store the posed '''Input Surface'''.
* '''Output mesh''': Select the tetrahedral mesh that will contain the materials at each point of '''Tetrahedral mesh'''.
* '''Pose surface''': This will pose the '''Input Surface''' according to the posed '''Armature''' and the weight images from the given '''Weight images folder'''. If the surface was evaluated, this will automatically use the evaluated weight to compute the posed surface. If not it will read the weight from the '''Weight images folder''' to do so (slower). If the checkbox is activated, the CLI will automatically run anytime any of the input is modified. Otherwise, the CLI will only run once.
* '''Material file''': Select the file that contains the material properties such as Young modulus and Poisson ratio for each label value.
'''Advanced workflow'''
'''Advanced workflow'''
* '''Armature''': Select the posed input armature.
* '''Tetrahedral mesh''': Select the input mesh to apply material properties onto.
* '''Input surface''': Select the input surface that will be posed.
* '''Go To Material Property Reader''': Open the [[../MaterialPropertiesReader|Material property reader]] module to access further parameters.
* '''Weight images folder''': Select the folder where the weight images are.
* '''Go To Pose Surface Module''': Opens the [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/PoseSurface Pose Surface] module.


| align="right"|
| valign="top"|
[[Image:PoseArmaturePanel-1.0.png|thumb|550px|Pose armature panel]]
[[Image:BenderFEMWorkflow-6-ComputeWeights-2.0.png|thumb|550px|Compute weights panel]]
[[Image:BenderWorkflow-v1.1-5-ComputeWeights.png|thumb|550px|5-B)Compute armature weights]]
|}
|}


== 6) Pose labelmap ==
== 7) Pose armature (posing)==
The [[#5.29_Pose_armature_.28posing.29|Pose armature]] section guides the user into posing the armature for the final  [[#6.29_Pose_labelmap|Pose labelmap]] resampling.
 
'''Note:''' When opening this page, the current armature automatically switches to ''Pose'' mode.
 
{| width="100%"
{| width="100%"
| valign="top"|
| valign="top"|


===A) Resample labelmap with pose===
===A) Armatures===
 
Pose the armature by applying rotations to armature bones. You can directly pose the armature from the 3D view, if needed the [[../Armatures|Armatures]] module can provide more controls.
 
'''Note:''' At this point '''only the ''Pose''''' of the armature can be edited, if the "Rest" mode of the armature is changed, the skinned volume and bone weights must be recomputed.   
 
'''Simple workflow'''
* '''Armature''': The armature(rig) to pose. Once selected, click and drag any bone to rotate around its joint.
* '''Import Animation''': Import a pose from a BVH file. Please note that the number of bones in the BVH must be the same than the armature.
'''Advanced workflow'''
* '''Go Armature module''': Open the [[../Armatures|Armatures]] module to further control the armature and its posing (e.g. reset the current pose to its originals rest value).
 
===B) Simulate Pose ===
 
Transform the tetrahedral mesh according to the armature pose and the material properties.
 
'''Simple workflow'''
'''Simple workflow'''
* '''Output posed labeldmap''': Select the output labelmap that will store the posed '''Input labelmap'''.
* '''Output mesh''': Select the output mesh that will store the posed '''Input mesh'''.
* '''Apply''': This will pose the '''Input labelmap''' according to the posed '''Armature''' and the weight images from the given '''Weight images folder'''.
* '''Enable collision''': Run the simulation with or without collision detection. If enabled, the mesh will not self-intersect, however it slows down the computation.
* '''Simulate pose''': Pose the '''Input mesh''' according to the posed '''Armature'''.
'''Advanced workflow'''
'''Advanced workflow'''
* '''Armature''': Select the posed input armature.
* '''Armature''': Select the posed input armature.
* '''Input surface''': Select the input labelmap that will be posed.
* '''Input mesh''': Select the input mesh to transform with the armature pose.
* '''Weight images folder''': Select the folder where the weight images are.
* '''Skin surface''': Select the skin surface used for collision.
* '''Go To Pose Labelmap Module''': Opens the [http://public.kitware.com/Wiki/index.php?title=Bender/Documentation/1.0/Modules/PoseLabelmap Pose Labelmap] module.
* '''Bone material''': Set the value of the bone label used internally to threshold the tetrahedral mesh to apply forces only on the bones.
* '''GUI''': Show the Sofa GUI to control the simulation.
* '''Go To Simulate Pose module''': Open the [[../SimulatePose|Simulate Pose]] module to choose more parameters.


| align="right"|
| valign="top"|
[[Image:PoseLabelmapPanel-1.0.png|thumb|550px|Pose labelmap panel]]
[[Image:BenderFEMWorkflow-7-PoseArmature-2.0.png|thumb|550px|Pose armature panel]]
[[Image:BenderFEMWorkflow-v2.0-7-SimulatePose.png|thumb|550px|7)Pose armature]]
|}
|}
= Similar Modules =
* Used modules
** Bender modules: [[../Armatures|Armatures]], [[../ChangeLabel|Change Label]],  [[../ComputeArmatureWeight|Compute Armature Weight]], [[../ModelQuadricClusteringDecimation|Model Quadric Clustering Decimation]], [[../PoseSurface|Pose Surface]], [[../PoseLabelmap|Pose Labelmap]], [[../SampleData|Sample Data]], [[../SkinModelMaker|Skin Model Maker]], [[../VolumeSkinning|Volume Skinning]]
** Slicer modules: [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/GrayscaleModelMaker Grayscale Model Maker], [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/Models Models], [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/ModelMaker Model Maker], [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/Volumes Volumes], [http://wiki.slicer.org/slicerWiki/index.php/Documentation/4.1/Modules/VolumeRendering Volume Rendering]


= Developer Information =
= Developer Information =
This module is a Python script module that can be manually edited for custom behavior (even in the installed version of Bender).

Latest revision as of 13:41, 1 April 2014

Introduction

The Workflow module guides the user step-by-step into transforming a volume using a rigging, skinning and posing technique using a multimaterial tetrahedral mesh and Finite Element Method (FEM).

Typically, the anatomical pose of a voxelized model is limited by the imaging device used to acquire the underlying data, e.g., MRI and CT scanners have narrow entries. Changing the pose of an already acquired voxelized anatomical model enables new processing of human anatomy in a wide variety of poses. The workflow module allows an operator to specify a rigging that represents the anatomical pose of an existing voxel model, manipulate that rigging into a different anatomical pose, and then generate a new voxelized model that represents the original model resampled into that new position.

This module applies to voxelized models the Skeletal animation technique initially conceived for surfaces.

Details

Author: Julien Finet, Kitware
Contributor #1: Johan Andruejol, Kitware
Acknowledgements: This work is supported by the Air Force Research Laboratories.
Contact: Julien Finet

Use Cases


Tutorials

Parameters

Advanced properties

The Advanced properties can be shown or hidden by clicking on the BenderExpandIcon.png expanding button.

Settings

  • Workflow mode: Show/Hide advanced controls at each step of the workflow. There are 3 modes
    • Basic: Most of the parameters are hidden, it provides a very simple step by step workflow.
    • Intermediate: The main parameters are visible, the advanced options are hidden. In this mode, it is possible to go to the next step even without finishing the current step. It can be useful when starting a workflow not from scratch.
    • Advanced: Full control is given to the user, almost all the parameters are shown. The full list of parameters is available in the specific module panels that can be opened by clicking the "Go to XYZ" buttons.
  • Reload module: If the module script is edited, clicking the button reloads the script. It can be used to tweak the behavior of the module.
Settings panel

Data

  • Visible: Check/Uncheck the data (Volume or Surface model) to show/hide in the 2D and/or 3D views.
Data panel

Volume Rendering

The Volume Rendering section can volume render intermediate or final volume/labelmap.

  • Labelmap: Select the volume/labelmap you want to volume render. The checkbox next to labelmap controls whether the rendering is visible or not.
  • Label(s): List all the label(s) that should be visible (i.e. opacity > 0.), all the other labels will be hidden (i.e. opacity = 0.). Labels must be separated with a ',' (comma).
  • Crop: Show/Hide a cropping box to apply to the volume rendering. Any voxel outside the box will be hidden.
  • Go To Volume Rendering: Opens the Volume Rendering module. It gives full control over the volume rendering parameters such as the color and opacity transfer functions, shading, rendering quality...
Volume Rendering panel

1) Adjust labelmap

The Adjust labelmap is the first step of the workflow. The user selects here the volume to pose and can optionally prepare the volume before any further computation is applied.

A) Labelmap

This section makes sure the input labelmap has the right color table associated with it and is in the right coordinate system.

Simple options

  • Volume: Select the volume/labelmap that you want to reposition. Read here the instructions to load data into Bender. The choosen volume will be automatically set as the default volume for all the following steps.
  • Colors: Select the color transfer function to apply to the volume. It is assigned to the volume automatically once selected. For each voxel intensity, a unique color is associated and is used at display time. It is important to select the right transfer function of the volume because the color names in the color transfer function are used in the Merge labels section. Grayscale means the volume is not a labelmap and there is no color transfer function associated to it.

Advanced options

  • Go to Volumes module: Go to the Volumes module to read volume information (such as its size, origin, spacing, scalar type, range...) and display properties (window/level, threshold, interpolation...)
  • Go to Label Statistics module: Go to the Label Statistics module to compute statistics for each label of the loaded labelmap.
  • LPS <-> RAS: Apply a (-1,-1, 1) transform to the volume. It can be used to apply the same coordinate system used by Bender to the volume. The "R,L,A,P,S,I" letters on the purple box in the 3D view represent the orientations "Right, Left, Anterior, Posterior, Superior, Inferior". Other transforms are available as well when opening the button's menu:
    • Posterior <-> Anterior flips the image around the posterior anterior plane.
    • Superior <-> Inferior flips the image around the superior/inferior plane.
    • Center translates the image to the origin.
Adjust labelmap panel

2) Merge and resample

The 2) Extract bone and skin page creates the bone and skin surface models to interactively control the posing.

A) Merge labels

Some labelmaps can have multiple labels for representing bones (e.g. bone marrow, bone cancellous, skull...). This section provides the functionality of merging the bones labels and the skin labels of the input labelmap to simplify the visualization and usability of the bones and the skin. It is important to merge those similar labels into a unique label (1 for the bones, 1 for the skin) as the Bender workflow handles only 1 label for the bones and 1 label for the skin. .

Simple options

  • Output Labelmap: Select the output labelmap that will contain all the labels of the input labelmap and the merged labels.
  • Merge Labels: Merge all the Input Labelmap labels into their corresponding labels given by the table.

Advanced options

  • Input Labelmap: Select the input labelmap that needs labels to be merged together. By default, it is Volume in A) Labelmap.
  • The table: The table lists all the labels that will be merged in one of the label categories. The different possible label categories are listed on the left side of the table. These labels corresponds from top to bottom to:
    • Background
    • Bone
    • Muscle
    • Skin

One the right side of each of those labels is listed all the labels that will be changed into one of them. These labels are automatically selected from the input volume color table (set in A) Labelmap) by looking for color names containing the strings corresponding strings.

  • Go To Change Label: Open the Change Label module to merge other labels together or simply change label values.

B) Resample image

This section resamples the input merged labelmap using the Voting Resample module. This allow the mesh computation in Create Tetrahedral Mesh to be faster and lighter. The Voting Resample module is used here to make that the Bone and Skin and Muscle are not resampled in place of the background.

Simple options

  • Output labelmap: Select the output labelmap under which the resampled image will be stored.
  • Scale factor: Precise here the scale factor by which the Input Labelmap will be resampled down. The higher the factor is, the faster subsequent computation on the mesh will be. However this implies a loss of details which can lead to a mesh poorly representing the original data.
  • Resample: Using a voting scheme and the High and Low precedence labels, downsample the Input labelmap.

Advanced options

  • Input labelmap: Select the labelmap to resample from.
  • High precedence labels: When downsampling an image, the algorithm must choose between labels to pick from for the new image. High precendence labels are always picked over the other labels. Order matters here as the first High precendence label is the label with the most precedence. In the workflow case, the precedence order is always Skin, Bone and Muscle. This allows us to make sure that the resampling does not change any of the image data to background.
  • Low precedence labels: Much like the High precendence labels, Low precendence labels help to decide what label is picked over which when resampling. Low precendence labels are never picked over the other labels. Order matters here as the first Low precendence label is the label with the least precedence. In the workflow case, the background is used.
  • Go To Voting Resample: Open the Voting Resample module to access more controls over the resampling.

C) Pad Image

This section simply pads the resample image of a few voxels to prepare it for the mesh generation using the Pad Image module.

Simple options

  • Output labelmap: Select the output for padded labelmap.
  • Pad thickness: Select the number of voxels of padding added around the Input labelmap. Two voxels is enough for the Create Tetrahedral Mesh module. More voxels can slow down the computation.
  • Pad: Add extra padding voxels around the Input labelmap.

Advanced workflow

  • Input labelmap: Select the labelmap volume to add voxels to.
  • Pad value: Set the value of the voxels added to the Input labelmap. In this case, the value added is the background label.
  • Go To Pad Image Module: Open the Pad Image module.
Extract bone and skin panel
2-A)Merge labels
2-B) and 2-C)Resample image and Pad image

3) Extract materials

The 3) Extract materials page generates a multi-material tetrahedral mesh from the image and extracts bone and skin surface models to interactively control the posing.

A) Create tetrahedral mesh

In a FEM workflow, repositioning happens on a tetrahedral mesh instead of a labelmap volume. This section generates tetrahedrals with associated material for each voxel.

Simple options

  • Output Mesh: Select the output that will contain the tetrahedral mesh.

Advanced options

  • Merged labelmap: Select the input labelmap that contains a limited number of materials (up to 3). By default, it is Output labelmap in 2.C) Pad image.
  • Pad image: If non zero labels are at the border of the image, pad the image for correct results. This option is not required if the image has previously been padded in 2.C) Pad image.
  • Go To Create Tetrahedral Mesh module: Open the Create Tetrahedral Mesh module to generate the tetrahedral mesh.

B) Extract bone mesh

This section extracts the bone material from the input tetrahedral mesh.

Simple options

  • Output bone mesh: Select the output mesh where the result mesh will be stored.
  • Extract bone model: Generate the bone model using the Volume Material Extractor module. The extracted bone mesh is used when placing or adjusting the armature by ensuring the armature bones are on top of the labelmap bones.

Advanced options

  • Input mesh: Select the tetrahedral mesh to extract the bone label from.
  • Bone material: Select the label in the input mesh to create the bone mesh from. By default, it is the Bone Label value in Merge labels.
  • Go To Volume Material Extractor module: Open the Volume Material Extractor module to access more controls over the model extraction parameters.

C) Extract skin mesh

This section extracts the surface of the skin label in the input labelmap volume. The algorithm is different than Extract bone mesh because it solely needs the information of the background label. It creates an outer surface of the Foreground labels (all the labels that are not "Background").

Simple options

  • Output skin model: Select the output model for the skin model.
  • Show/Hide skin: Toggle the visibility of the generated model in Output skin model.
  • Extract skin mesh: Using the Grayscale Model Maker, extract the outer surface of the Input Labelmap. The skin surface is used to enable collision when reposing the entire tetrahedral mesh in 7) Pose Armature(posing).

Advanced options

  • Input labelmap: Select the labelmap volume to extract the skin model from.
  • Background label: Select the threshold used to differentiate the body in the labelmap (foreground) from the outside air (background). Default is 0.
  • Use skin label: Peel the skin from the input labelmap, this generates an eroded skin model.
  • Skin label: Value of the skin label
  • Output spacing: Controls the spacing of the points in the generated decimated mesh.
  • Smooth: Apply smoothing filter on the generated surface mesh. A smooth surface improves the collision detection at the 7) Simulate Pose step.
  • Go To Models: Open the Models module to change the created model properties such as name, opacity, color...
  • Go To Skin Model Maker: Open the Skin Model Maker module to access more controls over the model extraction parameters such as smoothing.
Extract materials panel
3-A)Create tetrahedral mesh
3-B)Extract bone mesh
3-C)Extract skin mesh

4) Create armature (rigging)

This section creates the rig of the volume to pose. Note: When opening this page, the view will automatically switch to 3D Only to help creating/visualizing the armature.

A) Armatures

Manually create or load an existing armature to fit on the bones of the volume to pose. The user is redirected to the Armatures module for manually editing (e.g. create/edit/remove a bone segment). The armature (either created or loaded) is the interface between the user and the transformations needed to pose the volume models. Note: Once completed, the armature rest positions should not be changed since it would require all the following computations to be updated as well. It is therefore highly encouraged to save the created armature in order to be able to restore it with Load armature from model.

Simple workflow

  • Select a Preset: Choose a preset armature to load in the workflow. The preset armature are the same available than in the Armatures module. Which armature to load can be chosen by expanding the button's menu. This also allows to open directly an armature from file by clicking the option Load armature from file.
  • Toggle Skin visibility: Same as Toggle Skin Visibility in Skin model maker. When dropping bones, bones are placed in 3D where the user click (X,Y) and at the depth (Z) of the closest surface model under the mouse cursor. It is advised to hide skin model when placing armature bones because you want them on the bones surface and not the skin surface .
  • Load armature from model: Open a dialog window to load an armature from a model file. See Armatures module for further details.
  • Go To Armature Module: Open the Armatures module to manually edit the armature by adding, moving, deleting bones in Rest mode. Armature display properties such as X-Ray mode, opacity, color or shape can also be modified.
4) Armature/Rig
4)Armatures

5) Volume skinning

Before computing the weights, the skinning volume must first be extracted. The skinning volume represents what bone influence the most a given voxel. For each voxel a unique bone index is assigned. This means that if we were to use binary weights (see Compute Armature Weight), a given voxel would rotate similarly to its associated bone in the skinned volume. Because the skinning might not produces perfect results (some voxels might be assigned the wrong bones), and because the skinned volume drives the weight computation, it can be useful to tweak the output skinned volume, most notably in joints area. The Editor module can be used to edit the labelmap.

Note: When opening this page, the view switches to Four Up.

A) Volume skinning

Simple workflow

  • Skin volume: Compute the skinned volume. The output skinned volume is a labelmap where each voxel of the input Volume is associated with a bone of the input Armature (voronoi style algorithm).

Advanced workflow

  • Volume: Select the labelmap volume to use for skinning.
  • Armature: Select the armature to skin Volume.
  • Output skinned volume: Select the volume that will contain the output skinned volume.
  • Go To Volume Skinning Module: Open the Volume Skinning module for advanced properties.

B) Edit volume skinning

Simple workflow

Advanced workflow

  • Skinned volume: Select the volume that will be modified in the editor. More information in the Editor module documentation.
Skin volume panel
4)Volume skinning

6) Compute weights

The Compute weights section assigns a weight for each voxel of the input volume. The weights represent how much a voxel is influenced by a bone. It is later used when posing the volume and computing the unique transform to apply at a voxel (by interpolating the influencing bones transforms).

A) Compute armature weight

Smooth the Skinned volume by computing weights in order to consider the influence of every bone on a given voxel.

Simple workflow

  • Output weight image folder: Select the folder where the weight images will be saved. You need to have user write access.
  • Compute weights: Compute the weight images. For each bone of the Armature, a weight image is created. A weight image stores by how much a given voxel of the Volume will be influenced when the associated bone moves. This computation is done by solving a heat-diffusion equation in which the bones of the volume represent the hot source. To increase computation speed, the input images are first downsampled by a scale factor. The resulting weight image is then upsampled back to the original image spacing.

Advanced workflow

  • Volume: Select the volume that will be used for weight computation. It should be the same as in A) Volume Skinning.
  • Armature: Select the armature associated with Volume. It should be the same as in A) Volume Skinning.
  • Input skinned volume: Select the skinned volume to use for its bone regions. It should be the (possibly edited) volume associated with the Volume and the Armature generated in A) Volume Skinning.
  • Background label: Treat the given pixel value as backgroung. It will not be part of the weight computation.
  • Bone label: The bone label represents all the points of the labelmap which movement completely depend on one and only one bone of the armature. In the weights image, these points will either have the value 1 or 0 depending on their distance to the closest armature bone. In an anatomical study, this label should correspond to the bones of the patient. By default, the value is the same as the value used to extract the bones surface.
  • Padding: Defines how far (in voxel units) outside the body the weight region will be computed. This can be useful in certain case where one wants to pose a surface that doesn't exactly lies on the body (for example, the skin obtained with a simple grayscale Model Maker). However, padding can cause issue around joints (most notably the armpits) and isn't necessary when posing a labelmap.
  • Scale factor: The scale factor is used to speed up the processing. The weights are computated on downsampled version of the input labelmap according to this factor. These images are then up-sampled back to make sure they match the input image well. With a big scale factor, the computation will be faster but the weight images will be coarser.
  • Go To Compute Armature Weights module: Open the Compute Armature Weight module to further refine the computation of the weights by, for example, restricting it to a given bone or changing the downsampling ratio.

B) Evaluate weights

Evaluate weights at each vertices of the tetrahedral mesh.

Simple workflow

  • Output mesh: Select the output surface that will contain the evaluated weights at each point of Input surface.
  • Evaluate weights: For each point of the Input Surface, evaluate the influence (weight) of each bone and add the weights into field arrays (one point data array per bone). This improves the computational time of the Pose Surface.

Advanced workflow

  • Input mesh: Select the input surface that will have the weight evaluated on.
  • Weight images folder: Select the folder containing the weight image files.
  • Go To Evaluate Surface Weight module: Open the Evaluate weights module to access further parameters.

C) Material properties

Apply material properties at each vertices of the tetrahedral mesh.

Simple workflow

  • Output mesh: Select the tetrahedral mesh that will contain the materials at each point of Tetrahedral mesh.
  • Material file: Select the file that contains the material properties such as Young modulus and Poisson ratio for each label value.

Advanced workflow

  • Tetrahedral mesh: Select the input mesh to apply material properties onto.
  • Go To Material Property Reader: Open the Material property reader module to access further parameters.
Compute weights panel
5-B)Compute armature weights

7) Pose armature (posing)

The Pose armature section guides the user into posing the armature for the final Pose labelmap resampling.

Note: When opening this page, the current armature automatically switches to Pose mode.

A) Armatures

Pose the armature by applying rotations to armature bones. You can directly pose the armature from the 3D view, if needed the Armatures module can provide more controls.

Note: At this point only the Pose of the armature can be edited, if the "Rest" mode of the armature is changed, the skinned volume and bone weights must be recomputed.

Simple workflow

  • Armature: The armature(rig) to pose. Once selected, click and drag any bone to rotate around its joint.
  • Import Animation: Import a pose from a BVH file. Please note that the number of bones in the BVH must be the same than the armature.

Advanced workflow

  • Go Armature module: Open the Armatures module to further control the armature and its posing (e.g. reset the current pose to its originals rest value).

B) Simulate Pose

Transform the tetrahedral mesh according to the armature pose and the material properties.

Simple workflow

  • Output mesh: Select the output mesh that will store the posed Input mesh.
  • Enable collision: Run the simulation with or without collision detection. If enabled, the mesh will not self-intersect, however it slows down the computation.
  • Simulate pose: Pose the Input mesh according to the posed Armature.

Advanced workflow

  • Armature: Select the posed input armature.
  • Input mesh: Select the input mesh to transform with the armature pose.
  • Skin surface: Select the skin surface used for collision.
  • Bone material: Set the value of the bone label used internally to threshold the tetrahedral mesh to apply forces only on the bones.
  • GUI: Show the Sofa GUI to control the simulation.
  • Go To Simulate Pose module: Open the Simulate Pose module to choose more parameters.
Pose armature panel
7)Pose armature

Similar Modules

Developer Information

This module is a Python script module that can be manually edited for custom behavior (even in the installed version of Bender).