# stanfordnmbl/shoulder-personalization architecture

> Architecture diagram of the GitHub repository stanfordnmbl/shoulder-personalization, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stanfordnmbl/shoulder-personalization
- Repository: https://github.com/stanfordnmbl/shoulder-personalization

## Overview

This repository is a pair of OpenSim shoulder-model workflows: scaling a generic model from static and calibration recordings, then personalizing its shoulder-rhythm constraints from five poses per shoulder. Scaling estimates joint centers and humerus factors before OpenSim scaling, coordinate-system updates, and tracking-marker correction; personalization derives calibration coordinates and refits constraint functions, with optional independent clavicle elevation. Edges follow the sampled entry-point calls and module references; settings XML supplies parameters. Some internals are only partially excerpted, so the graph omits unverified links.

Main entry points: [`ModelPersonalization.py`](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/ModelPersonalization.py) (Personalization workflow), [`ModelScaling.py`](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/ModelScaling.py) (Scaling workflow), [`processing/scaling.py`](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/scaling.py) (OpenSim scaling), [`processing/score.py`](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/score.py) (SCoRE calibration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflows["Model workflows"]
  node_scale_entry["Scaling workflow<br/>[ModelScaling.py]"]
  node_personalize_entry["Personalization workflow"]
end

subgraph group_calibration["Calibration analysis"]
  node_score["SCoRE calibration<br/>[score.py]"]
  node_personalization["Pose fitting<br/>[personalization.py]"]
end

subgraph group_geometry["Frames and geometry"]
  node_coordinate_systems["Shoulder frames"]
  node_tools["Marker and fit utilities<br/>[tools.py]"]
end

subgraph group_scaling["Model scaling"]
  node_scaling["OpenSim scaling<br/>[scaling.py]"]
end

node_user(("Researcher"))
node_calibration_recordings["Calibration recordings"]
node_static_recording["Static recording"]
node_scaling_settings["Scaling settings"]
node_personalization_settings["Personalization settings"]
node_scale_setup["OpenSim scale setup"]
node_scaled_model["Scaled OpenSim model"]
node_personalized_model["Personalized model"]
node_independent_model["Independent clavicle model"]
node_opensim["OpenSim command"]

node_user -->|"runs"| node_scale_entry
node_user -->|"runs"| node_personalize_entry
node_scale_entry -->|"reads settings"| node_scaling_settings
node_personalize_entry -->|"reads settings"| node_personalization_settings
node_scale_entry -->|"calibrates from"| node_calibration_recordings
node_scale_entry -->|"scales from"| node_static_recording
node_scale_entry -->|"calls"| node_score
node_scale_entry -->|"calls"| node_scaling
node_scale_entry -->|"updates frames"| node_coordinate_systems
node_score -->|"uses"| node_tools
node_score -.-> node_coordinate_systems
node_scaling -->|"computes frames"| node_coordinate_systems
node_scaling -->|"reads marker data"| node_tools
node_scaling -->|"runs scale tool"| node_opensim
node_scale_entry -->|"uses"| node_scale_setup
node_scaling -->|"writes"| node_scaled_model
node_personalize_entry -->|"loads"| node_scaled_model
node_personalize_entry -->|"fits from"| node_calibration_recordings
node_personalize_entry -->|"calls"| node_score
node_personalize_entry -->|"calls"| node_personalization
node_personalization -->|"computes frames"| node_coordinate_systems
node_personalization --> node_score
node_personalization -->|"uses"| node_tools
node_personalize_entry -->|"fits constraints"| node_tools
node_personalize_entry -->|"saves"| node_personalized_model
node_personalize_entry -.->|"optionally generates"| node_independent_model

click node_scale_entry "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/ModelScaling.py"
click node_personalize_entry "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/ModelPersonalization.py"
click node_scaling_settings "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/settings_scaling.xml"
click node_personalization_settings "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/settings_personalization.xml"
click node_score "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/score.py"
click node_personalization "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/personalization.py"
click node_coordinate_systems "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/coordinate_systems.py"
click node_tools "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/tools.py"
click node_scaling "https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/scaling.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_scale_entry,node_personalize_entry toneBlue
class node_score,node_personalization toneAmber
class node_coordinate_systems,node_tools toneMint
class node_scaling toneRose
class node_user,node_calibration_recordings,node_static_recording,node_scale_setup,node_scaled_model,node_personalized_model,node_independent_model,node_opensim toneIndigo
class node_scaling_settings,node_personalization_settings toneTeal
```

## Components

### Model workflows

- [Scaling workflow](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/ModelScaling.py): `ModelScaling.py`
- [Personalization workflow](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/ModelPersonalization.py): `ModelPersonalization.py`

### Calibration analysis

- [SCoRE calibration](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/score.py): `processing/score.py`
- [Pose fitting](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/personalization.py): `processing/personalization.py`

### Frames and geometry

- [Shoulder frames](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/coordinate_systems.py): `processing/coordinate_systems.py`
- [Marker and fit utilities](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/tools.py): `processing/tools.py`

### Model scaling

- [OpenSim scaling](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/processing/scaling.py): `processing/scaling.py`

### Other components

- **Researcher**
- **Calibration recordings**
- **Static recording**
- [Scaling settings](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/settings_scaling.xml): `settings_scaling.xml`
- [Personalization settings](https://github.com/stanfordnmbl/shoulder-personalization/blob/main/settings_personalization.xml): `settings_personalization.xml`
- **OpenSim scale setup**
- **Scaled OpenSim model**
- **Personalized model**
- **Independent clavicle model**
- **OpenSim command**

## Connections

- Researcher → Scaling workflow: runs (evidence: `README.md`)
- Researcher → Personalization workflow: runs (evidence: `README.md`)
- Scaling workflow → Scaling settings: reads settings (evidence: `ModelScaling.py`)
- Personalization workflow → Personalization settings: reads settings (evidence: `ModelPersonalization.py`)
- Scaling workflow → Calibration recordings: calibrates from (evidence: `ModelScaling.py`)
- Scaling workflow → Static recording: scales from (evidence: `README.md`)
- Scaling workflow → SCoRE calibration: calls (evidence: `ModelScaling.py`)
- Scaling workflow → OpenSim scaling: calls (evidence: `ModelScaling.py`)
- Scaling workflow → Shoulder frames: updates frames (evidence: `ModelScaling.py`)
- SCoRE calibration → Marker and fit utilities: uses (evidence: `processing/score.py`)
- SCoRE calibration → Shoulder frames
- OpenSim scaling → Shoulder frames: computes frames (evidence: `processing/scaling.py`)
- OpenSim scaling → Marker and fit utilities: reads marker data (evidence: `processing/scaling.py`)
- OpenSim scaling → OpenSim command: runs scale tool (evidence: `processing/scaling.py`)
- Scaling workflow → OpenSim scale setup: uses (evidence: `README.md`)
- OpenSim scaling → Scaled OpenSim model: writes (evidence: `processing/scaling.py`)
- Personalization workflow → Scaled OpenSim model: loads (evidence: `README.md`)
- Personalization workflow → Calibration recordings: fits from (evidence: `ModelPersonalization.py`)
- Personalization workflow → SCoRE calibration: calls (evidence: `ModelPersonalization.py`)
- Personalization workflow → Pose fitting: calls (evidence: `ModelPersonalization.py`)
- Pose fitting → Shoulder frames: computes frames (evidence: `processing/personalization.py`)
- Pose fitting → SCoRE calibration (evidence: `processing/personalization.py`)
- Pose fitting → Marker and fit utilities: uses (evidence: `processing/personalization.py`)
- Personalization workflow → Marker and fit utilities: fits constraints (evidence: `ModelPersonalization.py`)
- Personalization workflow → Personalized model: saves (evidence: `ModelPersonalization.py`)
- Personalization workflow → Independent clavicle model: optionally generates (evidence: `README.md`)
