biobuddy 0.3.1
A generic interface to generate a virtual buddy
License: MIT
Requires Python: >=3.10



![biobuddy](https://github.com/user-attachments/assets/c8689155-0b26-4e13-835c-cdb6696e1acb)

`BioBuddy` is an open-source tool for [translating](#model-translation), [creating](#model-creation) and [personalizing](#model-personalization) musculoskeletal models across different formats (e.g., .osim, .bioMod). By enabling reliable interoperability between modeling environments, BioBuddy allows researchers to focus on scientific questions rather than technical constraints.

<!---
[![Actions Status](https://github.com/pyomeca/biobuddy/workflows/CI/badge.svg)](https://github.com/pyomeca/biobuddy/actions)
[![PyPI](https://anaconda.org/conda-forge/biobuddy/badges/latest_release_date.svg)](https://pypi.org/project/biobuddy/)
--->

[![codecov](https://codecov.io/gh/pyomeca/biobuddy/branch/main/graph/badge.svg)](https://codecov.io/gh/pyomeca/biobuddy)
[![Discord](https://img.shields.io/discord/1340640457327247460.svg?label=chat&logo=discord&color=7289DA)](https://discord.gg/Ux7BkdjQFW)

- [How to install](#how-to-install)
    - [Set-up environment (user)](#set-up-environment-user)
    - [Set-up environment (developer)](#set-up-environment-developer)
    - [Installing from source](#installing-from-source)
    - [Installing from conda-forge](#installing-from-conda-forge)
    - [Installing from pip](#installing-from-pip)
- [Features](#features)
  - [Model translation](#model-translation)
  - [Model creation](#model-creation)
  - [Model personalization/modification](#model-personalizationmodification)
      - [Scaling](#scaling)
      - [Joint center identification](#joint-center-identification)
      - [Merging segments](#merging-segments)
      - [Modifying the kinematic chain](#modifying-the-kinematic-chain)
      - [Flattening the model](#flattening-the-model)
- [Note](#note)
- [How to cite](#how-to-cite)
- [How to contribute](#how-to-contribute)


# How to install 
`BioBuddy` can be installed from source, from conda-forge, or pip.

### Set-up environment (user)
If you are a user, you can set up your environment with minimal dependencies.
```bash
conda install -c conda-forge python=3.11.11 pip
pip install scipy==1.15.1 numpy==1.25.2 lxml ezc3d plotly
```
Note: On mac, you might need to add `conda install conda-forge::libcxx`

And if you want to access all features, you will also need to install the following optional dependencies:
```bash
conda install -c conda-forge pyorerun rerun-sdk=0.21.0
```

### Set-up environment (developer)
However, if you are a developer and want to contribute, you will need to set up your environment using the following command before installing BioBuddy:
Due to the OpenSim dependency used only in BioBuddy's tests, we recommend using python=3.11.11
```bash
pip install pytest pytest-cov codecov
conda install -c opensim-org opensim=4.5.1
conda install -c conda-forge biorbd=1.11.2=py311h9439bbc_1 deepdiff
```

### Installing from source
Once you have set up your environment, you can install BioBuddy by running:
```bash
pip install .
```
from the root directory of the BioBuddy source code (the folder containing the file setup.py).

### Installing from conda-forge
You can also install BioBuddy from conda-forge by running:
```bash
conda install -c conda-forge biobuddy
``` 

### Installing from pip
You can also install BioBuddy from pip by running:
```bash
pip install biobuddy
```


# Features
## Model translation
You can load the original model using one of the `BiomechanicalModelReal().from_[format]` methods, and then export it 
into another format using the `BiomechanicalModelReal.to_[format]` method (see [example](examples/read_and_write_models.py)).
```python3
from biobuddy import BiomechanicalModelReal

# Read an .osim file
model = BiomechanicalModelReal().from_osim(
    filepath=osim_filepath,
    # Other optional parameters here
)

# Translate it into a .bioMod file
model.to_biomod(biomod_filepath)
```
See the example [read_and_write_models.py](examples/read_and_write_models.py) for more details.

## Model creation
A model can also be created from scratch using the `BiomechanicalModel`. In this generic model, everything can be defined 
through functions (i.e., without numerical values). The subject specific model (a `BiomechanicalModelReal`) can then be 
generated by evaluating the generic model with a motion capture trial. This feature is especially useful for kinematic 
models where the joint centers are defined based on anatomical marker placement (like in the plug in gait, see full 
[example](examples/create_model_from_c3d.py)). 

Here is a simple example of how to add components to such a model:
```python3

# Create the model
model = BiomechanicalModel()
de_leva = DeLevaTable(total_mass=60, sex=Sex.FEMALE)

# Add components to build the kinematic chain
model.add_segment(
    Segment(
        name="HEAD",
        parent_name="TRUNK",
        segment_coordinate_system=SegmentCoordinateSystem(
            "BOTTOM_HEAD",
            first_axis=Axis(name=Axis.Name.Z, start="BOTTOM_HEAD", end="HEAD_Z"),
            second_axis=Axis(name=Axis.Name.X, start="BOTTOM_HEAD", end="HEAD_XZ"),
            axis_to_keep=Axis.Name.Z,
        ),
        mesh=Mesh(("BOTTOM_HEAD", "TOP_HEAD", "HEAD_Z", "HEAD_XZ", "BOTTOM_HEAD")),
        inertia_parameters=de_leva[SegmentName.HEAD],
    )
)
model.segments["HEAD"].add_marker(Marker("BOTTOM_HEAD"))
model.segments["HEAD"].add_marker(Marker("TOP_HEAD"))
model.segments["HEAD"].add_marker(Marker("HEAD_Z"))
model.segments["HEAD"].add_marker(Marker("HEAD_XZ"))

# Evaluate the model with a motion capture trial
model_real = model.to_real(C3dData(c3d_filepath))
```
See the example [create_model_from_c3d.py](examples/create_model_from_c3d.py) for more details.

### Model components
There are many different components available to build a model (see this [example](examples/create_model.py) to see how to add those components to your model).

![Build_segment](docs/images/Build_segment.png)

### Inertial parameters 
As you might have noticed, the inertial parameters of the segments can be defined by hand or using anthropometric tables.
For now, only the table from DeLeva (1996) is implemented through the `DeLevaTable` class, but more tables will be added in the future.
A `DeLevaTable` can be initialized only using total height (normative segment proportions will be used) like this: 
```python3
de_leva.from_height(total_height=1.70)
```
or using more detailed measurements like this:
```python3
# From manual measurements or from marker positions
de_leva.from_measurements(
    total_height=1.70,
    ankle_height=0.07,
    knee_height=0.45,
    hip_height=0.98,
    shoulder_height=1.42,
    finger_span=1.72,
    wrist_span=1.53,
    elbow_span=0.85,
    shoulder_span=0.34,
    foot_length=0.34,
    hip_width=0.35,
)
```
or directly from a static trial (`.c3d` file) using markers placed on anatomical landmarks like this:
```python3
de_leva.from_static(static=C3dData(c3d_filepath))
```

Once you have set your table, you can extract the inertial parameters from one segment like this:
```python3
head_inertia_parameters = de_leva[SegmentName.HEAD]
```

or you can define a whole body model from a `DeLevaTable` like this:
```python3
model = de_leva.to_simple_model()
```
![DeLeva](docs/images/DeLeva.png)
![DeLeva_measures](docs/images/DeLeva_measures.png)


## Model personalization/modification
The current version of BioBuddy allows you to modify your `BiomechanicalModelReal` to personalize it to your subjects by:


### Scaling:
The scaling is performed by the `ScaleTool` which can be initialized from scratch like this:
```python3
original_model = BiomechanicalModelReal()

# Create the scaling configuration
scaling_configuration = ScaleTool(original_model)

# Add a scaling segment for the pelvis
scaling_configuration.add_scaling_segment(
    SegmentScaling(
        name="pelvis",
        scaling_type= SegmentWiseScaling(
            axis=Translations.XYZ,
            marker_pairs=[
                ["RASIS", "LASIS"],
                ["RPSIS", "LPSIS"],
            ]
        )
    )
)

# Add marker weights for the pelvis segment
scaling_configuration.add_marker_weight(MarkerWeight(name="RASIS", weight=1.0))
scaling_configuration.add_marker_weight(MarkerWeight(name="LASIS", weight=1.0))
scaling_configuration.add_marker_weight(MarkerWeight(name="RPSIS", weight=0.5))
scaling_configuration.add_marker_weight(MarkerWeight(name="LPSIS", weight=0.5))
```
or by reading from an existing file (e.g., `.xml` or `.biomod`) using the appropriate `ScaleTool.from_[format]` method.
Once the scaling configuration is set up, you can scale your model based on a static trial (`.c3d` file) and the total 
mass of your participant using the `ScaleTool.scale` like this:
```python3
# Performing the scaling based on a static trial
scale_tool = ScaleTool.from_biomod(biomod_filepath)
scaled_model = scale_tool.scale(static_trial=C3dData(filepath), mass=mass)
```
See the example [scaling_model.py](examples/scaling_model.py) for more details.

For now, there are three scaling methods available:
- `BodyWiseScaling`: scales the entire body based on the total height of the participant.
- `SegmentWiseScaling`: scales the segment based on the distance between marker pairs.
- `AxisWiseScaling`: scales each axis of the segment independently based on the distance between marker pairs.
![scaling_types](docs/images/Scaling_with_names.png)

### Joint center identification:
The `JointCenterTool` allows you to identify the joint centers of your model based on the movement of segments during 
functional trials.
First, you need to define the joint center configuration using `JointCenterTool.add()` method to define the joint 
you want to modify.
Then, you can use the `JointCenterTool.replace_joint_centers()` method to modify each joint.
```python3
from biobuddy import JointCenterTool

# Set up the joint center identification tool
joint_center_tool = JointCenterTool(scaled_model)
# Example for the right hip
joint_center_tool.add(
    Score(
        functional_trial=C3dData(c3d_filepath, first_frame=100, last_frame=900),
        parent_name="pelvis",
        child_name="femur_r",
        parent_marker_names=["RASIS", "LASIS", "LPSIS", "RPSIS"],
        child_marker_names=["RGT", "RUB_Leg", "RUF_Leg", "FBF_Leg", "RMFE", "RLFE"],
    )
)
# Example for the right knee
joint_center_tool.add(
    Sara(
        functional_trial=C3dData(c3d_filepath),
        parent_name="femur_r",
        child_name="tibia_r",
        parent_marker_names=["RGT", "RUB_Leg", "RUF_Leg", "FBF_Leg"],
        child_marker_names=["RATT", "RUB_Tib", "RDF_Tib", "RDB_Tib", "RSPH", "RLM"],
    )
)

# Perform the joint center identification
modified_model = joint_center_tool.replace_joint_centers()
```
See the example [replace_joint_centers_functionally.py](examples/replace_joint_centers_functionally.py) for more details.

For now, two algorithms were implemented `SCoRE` to locate the position of the joint center and `SARA` 
to identify the joint axis of rotation. Please note that in both cases, all segment components stay the same, only the 
joint position and axis are modified.

![SCoRE_SARA](docs/images/SCoRE_SARA.png)


### Merging segments:
The `MergeSegmentTool` allows you to merge two segments into one (including inertial parameters and all the components on the segment).
You can define which segments you want to merge using `SegmentMerge`, which requires the names of the segments to merge and the name of the new segment.
```python3
merge_tool = MergeSegmentsTool(original_model)
# By default, segments merge together setting the new segment coordinate as the mean of the old coordinates
merge_tool.add(
   SegmentMerge(
      name="LOWER_ARMS", 
      first_segment_name="L_LOWER_ARM", 
      second_segment_name="R_LOWER_ARM",
   )
)
# But you can also merge one segment on top of another one by specifying the segment coordinate system to keep
merge_tool.add(
   SegmentMerge(
      name="R_LOWER_ARM_AND_HAND", 
      first_segment_name="R_LOWER_ARM", 
      second_segment_name="R_HAND", 
      merged_origin_name="R_LOWER_ARM",
   )
)
modified_model = merge_tool.merge()
```
See the example [create_a_population_of_models.py](examples/applied_examples/create_a_population_of_models.py) for more details.

![merge_segments](docs/images/merge_segments.png)


### Modifying the kinematic chain:
The `ModifyKinematicChainTool` allows you to modify the kinematic chain of your model.
For now, the only modification available is to change which segment is the first segment of the kinematic chain (`ChangeFirstSegment`).
It inverts all segments between the original first segment and the new first segment.
```python3
kinematic_chain_modifier = ModifyKinematicChainTool(original_model)
kinematic_chain_modifier.add(ChangeFirstSegment(first_segment_name="FOOT"))
modified_model = kinematic_chain_modifier.modify()
```
See the example [create_a_population_of_models.py](examples/applied_examples/create_a_population_of_models.py) for more details.

![kinematic_chain_modifier](docs/images/kinematic_chain_modifier.png)


### Flattening the model:
The `FlatteningTool` allows you to transform a 3D into a 2D model.
It projects all segment components (com, muscle via points, ...) on the plane orthogonal to the `axis` specified.
Please note that for now the following components are not modified automatically (i.e., same as the original model):
- Inertia (which should not have an impact of the model is used in a 2D simulation)
- Degrees of freedom (these should be modified by the user after flattening the model)
```python3
symmetry_tool = FlatteningTool(model, axis=Translations.Z)
model = symmetry_tool.flatten()
```
See the example [simplify_an_arm_model.py](examples/applied_examples/simplify_an_arm_model.py) for more details.


## Other useful features
### MarkerData classes
When providing a motion capture trial (`static_trial` or `functional_trial`), you can provide a `C3dData` class to read and manipulate a `.c3d` files.
```python3
c3d_data = C3dData(c3d_path, first_frame, last_frame)
```
Similarly, you can use the `CsvData` class to read and manipulate `.csv` files.
But if you want to create your own data class, you can inherit from the abstract `MarkerData` class.


# Note
Understandably, not all modeling formats have the same functionalities, so some features may not be available for all 
formats. We will try to keep here a list up to date of the features that are available in BioBuddy that are not 
available for each format: 
 - biorbd (.bioMod):
   - `PathPointCondition` is not implemented yet in biorbd. So if your BioBuddy model has this component, we recommend running `BiomechanicalModelReal.fix_via_points(q)` before `BiomechanicalModelReal.to_biomod(path)`. This will evaluate the via point conditions at the desired posture (which should be close to the range of motion during the movement studied). If the condition is not meet, the via point is inactive, so it is removed from the model. Please note that this is a destructive operation, once the conditions are evaluated, they are removed from the model and the remaining via points are fixed on the segments. 
   - `PathPointMovement` are not implemented yet in biorbd. So if your BioBuddy model has this components, we recommend running `BiomechanicalModelReal.fix_via_points(q)` before `BiomechanicalModelReal.to_biomod(path)`. This will fix the position of the moving via points, muscle origin, and muscle insertion by evaluating the position function at the desired posture (which should be close to the range of motion during the movement studied). Please note that this is a destructive operation, once the movements are evaluated, they are removed from the model and the remaining via points are fixed on the segments.  

# How to cite
```
@software{biobuddy_2025,
  author       = {Eve Charbonneau, Pierre Puchaud, Teddy Caderby, Mickael Begon, Amedeo Ceglia, Benjamin Michaud},
  title        = {Bringing the musculoskeletal modeling community together with BioBuddy},
  month        = april,
  year         = 2025,
  publisher    = {Congrès de la Société de biomécanique},
  url          = {https://github.com/pyomeca/biobuddy}
}
```

# How to contribute
Our goal is to support as many musculoskeletal model formats as possible, so do not hesitate to contact us if you'd like to see your favorite format supported by BioBuddy. 
If you are using BioBuddy and encounter any problem, please open an issue on this GitHub repository. 
We are also open to suggestions for new features or improvements to existing functionality.
All contributions are welcome!