Positioning with PIPER

After the Overview, you'll find detailed step-by-step instructions on this page.

The PIPER metadata for VIVA+ is available at model/preprocess/PIPER_Metadata in the repo.

Overview

We recommend applying the following steps to position the model in PIPER:

1. Load PIPER Metadata.

2. Load Environment Model.

3. Start Positioning:

   • Fix bones that should not be positioned (for arms, also fix the clavicle and scapula).
   • It is recommended to use the joint controller for positioning and to switch off collision detection.
   • Adjust spring stiffness if necessary.
4. Use Python scripting for set up the positioning simulation.
   Check for ID conflicts with the model!
5. Run pre-simulations (positioning simulation).
   • Global damping is recommended.
6. Export new nodal coordinates from the d3plots.
7. Fix joint node inconsistencies:
   • Due to numerical issues (e.g., rounding), some joint nodes may not be coincident after exporting. This may lead to error termination when starting the positioned model. A Jupyter notebook has been provided to fix these issues and restore coincident joint nodes.

Refer to the following documentation for more information:

http://piper-project.org/

https://gitlab.com/piper-project.org/application/-/wikis/tutorials/example2

https://gitlab.com/piper-project.org/application/-/wikis/tutorials/position_by_FE_simul

---

Detailed Instructions

The following instructions are based on the PIPER positioning tutorial authored by DI Christoph Leo and DI Dr. Corina Klug from Graz University of Technology, and have been updated by Dr. Shinya Abe from Chalmers University of Technology.

Background

In this tutorial, you will learn how to reposition the VIVA+ models using PIPER. PIPER can reposition Human Body Models (HBM) visually using the Positioning module. It can also create input decks for a finite element (FE) simulation to bring the HBM from the initial posture into the target position. Using finite element simulation can avoid initial penetrations (e.g., bone collisions) and improve mesh quality.

Prerequisites

To successfully complete the following steps, ensure you have the following prerequisites:

• Download the current version of PIPER.
• Download the current version of VIVA+ model.
• Download the current version of PIPER Metadata for the VIVA+ model.
• Download the Jupyter Notebook for transforming the positioning FE simulation results back to the VIVA+ model.

Outcomes

By the end of this tutorial, you will be able to:

• Position the VIVA+ models using PIPER.
• Create input decks for a positioning FE simulation using PIPER.
• Transfer the results (nodal coordinates) of the positioning FE simulation to obtain the positioned model for further use.

VIVA+ 50F Standing as Example

In this guide, VIVA+ 50F-standing model will be used as an example. However, the same procedure can be applied to other VIVA+ models such as 50M-standing, 50F/M-seated models.

VIVA+ 50F-standing model can be found in the vivaplus\model\50F-standing folder of the repo.

1. Load the VIVA+ model in PIPER

Working Directory

From now on, we assume your working directory is:

C:\Users\xxxx\PIPER_trial\

This directory will also be referred to as the PIPER Metadata folder.

The following PIPER Metadata for the VIVA+ model should be located in this folder:

• PIPER_vivaplus_description_LSDyna.pmr
• PIPER_run_vivaplus.key
• PIPER_entities_vivaplus.key

Important: Your working directory must not contain any spaces.
Using spaces will cause problems with Python scripting in PIPER (Section 2.3).

• ✅ Good example: C:\Users\xxxx\PIPER_trial\
• ❌ Bad example: C:\Users\xxxx\PIPER trial\

1. File Preparation and Setup

   Note that PIPER does not allow changing directories when loading files. All required files must be located in the same folder. Therefore, the VIVA+ files need to be copied to the same folder as the PIPER Metadata files. The required files are illustrated here using the VIVA+-50F-standing model as an example:

   • Copy all files from the 50F-standing folder (vivaplus\model\50F-standing) into the PIPER Metadata folder.
   • Copy all files from the common folder (vivaplus\model\common) into the PIPER Metadata folder.
   • Update the include file in the PIPER Metadata file (PIPER_run_vivaplus.key) to point to the main .key file of the model you just copied (e.g., vivaplus-50F-standing.key or vivaplus-50F.key).

   

   • After completing the steps above, you can import the PIPER Metadata PMR file (PIPER_vivaplus_description_LSDyna.pmr) in PIPER.

2. How to Import the VIVA+ Model in PIPER

   • Open PIPER application.
   • In the upper-left of the PIPER application, click the Project menu.
   • Select Import → Import HBM Model.
   • Selecte the file PIPER_vivaplus_description_LSDyna.pmr from the PIPER Metadata folder.

For more information about the PIPER application, see PIPER Graphical User Interface.

2. Position the VIVA+ Model in PIPER

After importing the VIVA+ model, you can start positioning it in PIPER. The following instructions describe one way to perform positioning in PIPER. For more details, please refer to the comprehensive documentation of the Pre-Positioning Module, which describes all positioning functions available in PIPER.

The recommended workflow, or "Golden Path", for positioning the VIVA+ model using PIPER is as follows:

1. (Optional) Load Environment Model.
   • If needed, you can import environment models, such as vehicle seats, bicycles, or other objects. Each model can be scaled and positioned individually to help determine the correct target position of the HBM.
     To import an environment model:
     Project → Environment Models → select the file → add environment model file.

2. Start Positioning. (For more information about positioning, see the PIPER documentation).

   • Switch to the Pre-Positioning Module (loading this module may take a few minutes).
   • Deactivate bone collision for physics-based positioning: Control → Deactivate Collision.
     
   • Fix bones that should be not positioned (for arms, also fix the clavicle and scapula).
     To do this: Fixed Bones → select the bones to exclude from positioning.
     In this guide, the following bones are fixed as an example: head, body proper, left clavicle, and left scapula.
   • It is recommended to use the Joint Controller for positioning. Positioning can also be performed using the Landmark, Frame, or Spine Controller, but the Joint Controller has proven to work best. Examples of positioning using the Landmark and Frame Controllers will be provided at the bottom of this page (currently under construction).
     To use the Joint Controller:
     • Select the joint to be positioned and add it by clicking the green + button. (Multiple joints can be added for positioning.)
     • Activate Frame to display the coordinate system in the model.
     • In this guide, the following joints are adjusted: Left_glenohumeral, Left_hip, Left_knee, Right_hip and Right_knee.
   • Activate Positioning.
     • Click Positioning in the upper-right corner, or in the Control panel.
   • Now you can adjust the values of the Joint Controller until the target position is reached.
     • (Optional) If larger displacements are required, you can adjust the spring stiffness k (maximum: 1e+10).
     • Adjust the values gradually, one joint at a time.
     • In this guide, the positioning was continued until the following position was reached:
     • Take a screenshot of the Joint Controller panel (right side of the figure above) or record the final values of each joint. These will be used in the next section (3. Python Scripting in PIPER), e.g.:
       • Left_glenohumeral: rx=100°, ry=0°, rz=35°
       • Left_hip: rx=-35°, ry=0°, rz=0°
       • Left_knee: rx=35°, ry=0°, rz=0°
       • Right_hip: rx=-45°, ry=0°, rz=0°
       • Right_knee: rx=-50°, ry=0°, rz=0°

   • (Optional) Save the target position as a model, as well as the project:

     • Saving a model: In the Update model panel, click All nodes → click Update → enter a name for the model (without spaces) → click OK
     • Saving as the project: Project → Save as → enter file name → Save

     Saving the model or project is not required to proceed to the next step

     Saving the model or project is not required to proceed to the next step. You only need a screenshot of the Joint Controller panel showing the target position (DOF of each joint) or the recorded rx, ry, and rz values of each joint.

   • Close the current PIPER session.

3. Python Scripting in PIPER

   Using the final DOF values (rx, ry, rz) of each joint from the previous step, you can create the positioning FE simulation input decks with Python scripting in PIPER.

   For more information, see the PIPER Scripting Documentation or the Tutorial on YouTube.

   Please, repeat the following steps from the previous sections:

   • Open a new PIPER session.
   • Import the VIVA+ model in its default posture (before positioning) in PIPER.
   • Switch to the Pre-Positioning Module.
   • Deactivate bone collision for physics-based positioning: Control → Deactivate Collision.
   • Fix the bones that should not be positioned. In this guide, fix the head, body proper, left clavicle, and left scapula.
   • Set up the Joint Controller with the same joints as in the previous section (2. Start Positioning). In this guide, the following joints are adjusted: Left_glenohumeral, Left_hip, Left_knee, Right_hip and Right_knee. Activate Frame to display the coordinate system in the model and increase the spring stiffness k to 1e+10.
   • Important: Do not activate Positioning yet.

   Next, follow the steps below to run the Python script in PIPER to create the positioning FE simulation input decks:

   • Create a new folder named export in the PIPER Metadata folder. This folder will store the positioning FE simulation input decks generated by the Python script. C:\Users\xxxx\PIPER_trial\export
   • Click All Nodes in the Update Model panel → enable the bar on the right side of Scripting → click Scripting.
   • In the Run a Python Script panel, select Positioning_FE_auto.py from Standard.

   • Specify Arguments: Insert the following:
     C:\Users\xxxx\PIPER_trial\export\ import_model ['Left_glenohumeral','Left_hip','Left_knee','Right_hip','Right_knee'] [[100,'nan',35],[-35,'nan','nan'],[35,'nan','nan'],[-45,'nan','nan'],[-50,'nan','nan']] 6

     This is where you need the screenshot of the Joint Controller or the recorded final DOF values of each joiont from the previous section (2. Start Positioning).
     

     How to Write Arguments

     Important: The argument is sensitive to spaces. Follow the instructions below carefully.

     • The 1^st argument is the path to the export folder you just created.
       Important: Make sure the path does not contain any spaces.

       C:\Users\xxxx\PIPER_trial\export\

     • The 2^nd argument is import_model (use an underscore between words).

       import_model

     • The 3^rd argument is a list of joints. In this guide, it is as follows.

       ['Left_glenohumeral','Left_hip','Left_knee','Right_hip','Right_knee']

     • The 4^th argument is a list of lists containing the final DOF values (rx, ry, rz) of each joint. This is where the screenshot of the Joint Controller or the recorded final DOF values of each joiont from the previous section (2. Start Positioning) is used. In this guide, it is as follows.

       [[100,'nan',35],[-35,'nan','nan'],[35,'nan','nan'],[-45,'nan','nan'],[-50,'nan','nan']]

       • Each inner list corresponds to a joint in the same order as in the 3^rd argument. Each inner list contains three values representing the DOF (rx, ry, rz) of the corresponding joint. For example, for the Left_glenohumeral joint, the target position is rx=100°, ry=0°, and rz=35°, which is represented as [100,'nan',35] in the 4^th argument.
       • Use nan for any DOF that should not be changed. For example, if only rx and rz of a joint should be changed, set ry to nan, as shown in the example above.

     • The 5^th argument is the number of intermediate steps PIPER takes to reach the target position. Use a larger number of steps if a large displacement is required. In this guide, it is set to 6.

     • Lastly, the entire argument should be written as a single line without any line breaks.
       Important: Insert a single space between the arguments.
       C:\Users\xxxx\PIPER_trial\export\ import_model ['Left_glenohumeral','Left_hip','Left_knee','Right_hip','Right_knee']
[[100,'nan',35],[-35,'nan','nan'],[35,'nan','nan'],[-45,'nan','nan'],[-50,'nan','nan']] 6

   • In the Run a python script panel, click Open to execute the script.

   • Ensure there are no error messages in the Console panel at the bottom of the PIPER application. If any errors appear, check the arguments you entered.

   Finally, the positioning FE simulation input decks can be created and exported to the export folder. Perform the following steps:

   • Activate Positioning.
     • Click Positioning in the upper-right corner, or in the Control panel.
   • Observe the positioning process until it comes to a complete stop. With the intermediate steps set to 6 in this guide, the process will take 5-6 steps to reach the target position.

   

   • In the Joint Controller panel, ensure the target position is reached.
     • Check the rx, ry, and rz values of each joint.
   • Deactiveate Positioning.
     • Click Positioning in the upper-right corner, or in the Control panel.

   Check the export folder inside the PIPER Metadata folder. It should contain the following positioning FE simulation input files:
   

   Now, finally, it is ready to run the positioning FE simulation.

3. Positioning Finite Element Simulation

1. File Preparation and Setup

   • (Optional but Recommended) Duplicate the export folder and rename the copy to, for example, positioned_model.
     C:\Users\xxxx\PIPER_trial\positioned_model
     • Reason: If a mistake occurs during the upcoming Applying ID Offset process, you can revert to the original files stored in the export folder.
     • The positioned_model folder will then serve as the working directory to store the results of the positioning FE simulation.
   • Copy all files from the 50F-standing folder (vivaplus\model\50F-standing) into the positioned_model folder.
   • Copy all files from the common folder (vivaplus\model\common) into the positioned_model folder.

   • Copy recommended control cards vivaplus-recommended-control-cards.k from the vivaplus\model\recommended_control_cards folder into the positioned_model folder.

     Do Not Modify the *INCLUDE Entry Yet

     Do not change the *INCLUDE entry in main_pos.dyn (e.g., from main.key to vivaplus-50F-standing.key) yet.
     This will be performed after the Applying ID Offset process.

2. Applying ID Offset.
   Before running the positioning FE simulation, it is essential to check for ID conflicts between the VIVA+ model and the positioning FE simulation input decks. ID conflicts can lead to error termination during the simulation. To prevent this, apply an ID Offset to the positioning FE simulation input decks to ensure that all IDs are unique and do not overlap with those of the VIVA+ model.

   • Open the main_pos.dyn file (in the positioned_model folder) using LS-PrePost and save it again with an ID Offset (recommended: 9900000). In this guide, apply the ID Offset of 9900000 only to *DEFINE_CURVE.

     How to Apply ID Offset and Select the Input Variable (Recommended Method)

     1. Open LS-PrePost, then import main_pos.dyn from the positioned_model folder (File → Import → LS-DYNA Keyword File).
     2. Check the ID count (File → Save As → Save Keyword As → click "Offset").
     3. The following Save Keyword window will appear. Take a screenshot.
     4. Repeat steps a-c for vivaplus-50F-standing.key (or the main .key file of the VIVA+ model you are using). Take a screenshot of the ID count. For vivaplus-50F-standing.key, the ID count should appear as follows:
     5. Compare the ID counts (screenshots) of main_pos.dyn and vivaplus-50F-standing.key (or the main .key file of the VIVA+ model you are using) to identify any overlapping IDs.
        • In this guide, note that only the IDs of *DEFINE_CURVE in main_pos.dyn overlap with those in vivaplus-50F-standing.key.
     6. Repeat steps a and b for main_pos.dyn.
     7. Uncheck all input variable except *DEFINE_CURVE in the Save Keyword window. Enter 9900000 (recommended) in the Offset field. Click Set, and then Save to apply the ID Offset to main_pos.dyn.
     8. Save file (File → Save → Save Keyword).

3. Update *INCLUDE Entries in main_pos.dyn

   • Change main.k to vivaplus-50F-standing.key (the main .key file of the VIVA+ model copied into the positioned_model folder).

   • Include the recommended control cards vivaplus-recommended-control-cards.k as follows:
     

     Troubleshooting: Duplicate keyword

     Before solving the simulation, import main_pos.dyn into LS-PrePost to check whether the following warning message appears:

     WARNING - Duplicate keyword: DATABASE_BINARY_D3PLOT
       Warning occurs in file C:\Users\xxxx\PIPER_trial\positioned_model\main_pos.dyn
     Data input seq. 2 from file main_pos.dyn
     Data input seq. 14 from file vivaplus-91-output-settings.k
     Last one will be used
     

     It will most likely appear. To resolve this issue, disable *DATABASE_BINARY_D3PLOT in vivaplus-91-output-settings.k by commenting it out with a $ at the beginning of the lines.

4. Run the Positioning FE Simulation
   The positioning FE simulation is now ready to be solved using an explicit dynamic FE soflver such as LS-DYNA.

   • Use the main_pos.dyn file in the positioned_model folder as the input deck for the positioning FE simulation.

     Global damping is recommended

     Use global damping in the positioning FE simulation:
     

4. Transfer Positioning FE Simulation Results to Create the Positioned VIVA+ Model

To transfer the results (nodal coordinates) of the positioning FE simulation and obtain the positioned model for further use, use the provided Jupyter Notebook file — node_transfer.ipynb. A detailed description is given in the notebook. However, please read below first!

Before running the Jupyter Notebook file — node_transfer.ipynb

Please make sure all VIVA+ files (those from vivaplus\model\50F-standing and vivaplus\model\common), node.k (created by following the instructions given in node_transfer.ipynb), and node_transfer.ipynb are all located in the same folder. For example, the existing positioined_model folder can be used, or a new folder can be created if preferred. If these files are not in the same folder, the numerical issue (see below) will not be fixed properly.

Due to numerical issues (e.g., rounding), some joint nodes may not be coincident after exporting from d3plot. This can lead to error termination when starting the positioned model. This Jupyter notebook also fixes these issues and restores coincident joint nodes.

In short, once positioned_nodes.k is obtained by running the Jupyter notebook, replace vivaplus_50F-standing_nodes.k with positioned_nodes.k in vivaplus-50F-standing.key.

5. Positioned VIVA+ HBM for Further Use

Now, the VIVA+ model (in this guide, the 50F-standing model) in its new posture is ready for further use, such as crash or other impact simulations. In this guide, the positioned model looks as follows:

If the desired target posture is difficult to achieve using the steps above, it is recommended to divide the positioning into multiple stages. In practice, this means repeating steps 1–4 several times, each time starting from the previously positioned model and incrementally moving closer to the desired target posture.

For additional (2^nd, 3^rd, ...) rounds of positioning

It is strongly recommended to remove nodes which were added from the previous positioning round. In the previous section 3.2 Applying ID Offset, the node ID count of the positioning FE simultion input decks ranged from 1 to 26652 (see below).
On the other hand, the node ID count of vivaplus-50F-standing.key starts from 1000000 (see below) This means all nodes before node ID 1000000 should be removed from positioned_nodes.k.
Please follow the instructions below:
1. Open positioned_nodes.k in a text editor.
2. Remove all nodes with node IDs less than 1000000, e.g., from node ID 1 to 26652.

This will make applying ID Offset in the next round of positioning much easier.

Additional Resources (Under Construction)

Positioning with Landmark and Frame Controllers.

• Positioning with Landmark Controller (Under Construction)
• Positioning with Frame Controller (Under Construction)