Native OpenSim C++ Integration for PhysioExperiment • PhysioOpenSim

Native OpenSim C++ Integration for PhysioExperiment

PhysioOpenSim provides direct access to the OpenSim musculoskeletal modeling library from R via Rcpp, without requiring Python or Java bridges. The package wraps model-level operations and simulation tool execution for seamless integration into biomechanics analysis workflows within the PhysioExperiment ecosystem.

OpenSim linkage is optional at build time. When the OpenSim C++ SDK is not detected, the package installs in fallback mode with informative runtime messages, ensuring that dependent packages can still be loaded.

Features

Build-Time Detection

PhysioOpenSim automatically locates the OpenSim SDK at install time using two strategies (checked in order):

pkg-config – pkg-config opensim
OPENSIM_HOME – environment variable pointing to the OpenSim installation root (inspects include/sdk/include and lib/sdk/lib)

If neither method succeeds, the package builds in fallback mode: opensimAvailable() returns FALSE and OpenSim-dependent calls return a descriptive error.

Availability Checks

Function	Description
`opensimAvailable()`	Whether the native C++ backend was linked at build time
`opensimBuildConfig()`	Detection method, include/lib paths, and build flags
`opensimCLIAvailable()`	Whether the `opensim-cmd` command-line tool is on `PATH`
`opensimCLIPath()`	Full path to the `opensim-cmd` executable

Model Operations

Function	Description
`opensimLoadModel()`	Load an `.osim` model file into memory
`opensimSaveModel()`	Save a model back to an `.osim` file
`opensimModelName()`	Get the model name
`opensimSetModelName()`	Set the model name
`opensimModelSummary()`	Bodies, joints, muscles, markers, forces summary
`opensimModelComponents()`	List all component paths in the model
`opensimModelInitialize()`	Initialize the model system
`opensimModelIsInitialized()`	Check initialization status
`opensimFinalizeConnections()`	Finalize model connections before simulation

Tool Execution

Each tool wrapper supports three execution backends selected by the execution argument:

"native" – calls the OpenSim C++ API directly (requires a native-enabled build)
"cli" – invokes opensim-cmd run-tool as a subprocess
"auto" (default) – uses native when available, otherwise falls back to CLI

All wrappers return a structured list containing execution backend used, stdout, stderr, exit status, and elapsed time for pipeline logging and reproducibility.

Function	Description
`opensimRunTool()`	Execute any OpenSim tool from a setup XML
`opensimRunIK()`	Inverse Kinematics
`opensimRunID()`	Inverse Dynamics
`opensimRunSO()`	Static Optimization
`opensimRunAnalyze()`	Analyze tool
`opensimRunCMC()`	Computed Muscle Control
`opensimRunRRA()`	Residual Reduction Algorithm

Setup XML Generation

Use existing OpenSim-generated setup XMLs as templates and programmatically replace tags from R. This enables batch processing of multiple trials without manual XML editing.

Function	Description
`opensimWriteToolSetupFromTemplate()`	Generic XML tag replacement
`opensimWriteIKSetupFromTemplate()`	Inverse Kinematics setup
`opensimWriteIDSetupFromTemplate()`	Inverse Dynamics setup
`opensimWriteSOSetupFromTemplate()`	Static Optimization setup
`opensimWriteAnalyzeSetupFromTemplate()`	Analyze tool setup
`opensimWriteRRASetupFromTemplate()`	RRA setup
`opensimWriteCMCSetupFromTemplate()`	CMC setup

Installation

From R-universe

install.packages("PhysioOpenSim",
                  repos = c("https://x-biosignal.r-universe.dev",
                            "https://cloud.r-project.org"))

From GitHub

# install.packages("remotes")
remotes::install_github("x-biosignal/PhysioOpenSim")

OpenSim-Enabled Build

To link against the OpenSim C++ SDK, make the SDK discoverable before installing:

Using pkg-config (Linux / macOS):

export PKG_CONFIG_PATH="/path/to/opensim/lib/pkgconfig:${PKG_CONFIG_PATH}"
R CMD INSTALL PhysioOpenSim

Using OPENSIM_HOME (Linux / macOS / Windows):

export OPENSIM_HOME="/path/to/opensim"
R CMD INSTALL PhysioOpenSim

The package requires C++17 and R >= 4.2.

Quick Start

library(PhysioOpenSim)

# --- Check availability ---
opensimAvailable()
#> [1] TRUE
opensimBuildConfig()
#> $detect_method
#> [1] "OPENSIM_HOME"
#> $include_path
#> [1] "/opt/opensim/sdk/include"
#> ...

# --- Load and inspect a model ---
model <- opensimLoadModel("gait2392.osim")
opensimModelName(model)
#> [1] "gait2392"
opensimModelSummary(model)
#> Bodies: 13, Joints: 13, Muscles: 92, Markers: 35

# --- Initialize for simulation ---
opensimModelInitialize(model)
opensimFinalizeConnections(model)

# --- Batch-process IK from a template ---
ik_setup <- opensimWriteIKSetupFromTemplate(
  template_file = "templates/ik_setup.xml",
  output_file   = "run/trial01_ik_setup.xml",
  model_file    = "model/gait2392.osim",
  marker_file   = "data/trial01.trc",
  output_motion_file = "results/trial01_ik.mot",
  time_range    = c(0.5, 1.5)
)

# --- Run Inverse Kinematics ---
result <- opensimRunIK(ik_setup$output_file, fail_on_error = FALSE)
result$execution
#> [1] "native"
result$status
#> [1] 0
result$elapsed
#> [1] 2.34

# --- Backend selection ---
result_cli <- opensimRunIK("setup_ik.xml", execution = "cli")
result_nat <- opensimRunIK("setup_ik.xml", execution = "native")

Dependencies

R (>= 4.2)
Rcpp (linked)
OpenSim C++ SDK (optional; graceful fallback when unavailable)

Ecosystem

PhysioOpenSim is part of the PhysioExperiment ecosystem, a suite of R packages for multi-modal physiological signal analysis.

Related packages:

Package	Role
PhysioExperiment	Core data model and signal processing
PhysioMoCap	Motion capture I/O and analysis
PhysioMSKNet	Musculoskeletal network analysis
PhysioAnnotationHub	Anatomical knowledge graph

Author

Yusuke Matsui

License

MIT

Governance & support

Part of the Physio ecosystem. Community and policy documents live in the umbrella repository: