OpenSim for Android · Built with GPT-6 Astra

Watch on YouTube

Originally created in collaboration with GPT-6 Astra, building on OpenSim and its contributors' work. The film introduces the SDK and workbench and shows a cycling inverse-kinematics example using noisy tracking data.

A reusable Android port of the OpenSim 4.6 C++ engine, with its upstream Java API accessible directly from Kotlin, a Kotlin convenience layer, a reusable GUI module and an Android workbench application. This is a community port, not an official OpenSim distribution or an Android reimplementation of its mathematics.

In development. See feature coverage and the validation ledger. An API existing in a generated wrapper does not establish device compatibility or numerical correctness for every model.

Modules

• opensim: native engine, all six upstream Java binding modules under org.opensim.modeling, and com.saifkhichi.opensim Kotlin conveniences.
• opensim-gui: embeddable Android workbench for model inspection, coordinate posing, motion review and guided setup forms plus advanced XML for OpenSim tools.
• opensim-models: optional offline starter-model catalogue with five stock OpenSim models and their geometry. Included in the workbench, not in the engine.
• demo: runnable application hosting the GUI; no account, cloud service or dependency on another application is required.
• native: pinned source acquisition, small Android patches and C-only reference BLAS/LAPACK. No Python runtime is embedded in the Android package.

The architecture reuses OpenSim's Java and Python binding foundation. Kotlin calls JNI, which runs the same C++ algorithms used by Python. This retains model formats, components and tools instead of recreating a small incompatible subset in Kotlin. Language-specific NumPy conveniences are not Kotlin APIs.

Build

Start with a clone of this repository; no sibling projects or desktop OpenSim installation are needed. See building from a fresh checkout for SDK setup, verification, output paths and independent app integration. Native compilation supports macOS and Linux hosts, not native Windows builds.

Requirements: Python 3.11+, Git, curl, CMake 3.22+, Ninja, SWIG 4.1.1+, JDK 17+, Android SDK 36 and NDK r28 or newer. The Gradle wrapper is included. NDK 29 has been selected for the initial build; see the validation ledger for tested hosts. Host Python only orchestrates the build. No Fortran compiler is required.

export ANDROID_HOME=/path/to/Android/sdk
export ANDROID_NDK_HOME="$ANDROID_HOME/ndk/29.0.13113456"
export JAVA_HOME=/path/to/jdk
# Optional isolated host SWIG installation, if swig is not already on PATH:
uv venv .tools
uv pip install --python .tools/bin/python swig==4.3.1

python3 native/build.py --abi arm64-v8a
./gradlew :opensim:assembleRelease :opensim-models:assembleRelease :opensim-gui:assembleRelease :demo:assembleDebug

For an additional architecture, repeat with --abi x86_64, --abi armeabi-v7a or --abi x86 (or repeat --abi in one invocation). Native builds have been produced for all four ABIs; only successfully built, integrity-verified ABIs are packaged. Runtime testing includes an arm64 emulator and two physical Google Pixel devices (Pixel 6 and Pixel 11 Pro). See the validation ledger for test scope and remaining architecture coverage. Native compilation is substantial; source/build caches remain in ignored .native/. Configuration, compilation and install logs are kept per ABI and dependency.

The package requires Android 8.0/API 26 or later. It cannot run on literally every Android device: the application's package must include the device's ABI, sufficient memory/storage must be available, and a model must not require unsupported plugins or solvers. Builds use 16 KiB ELF alignment for current Android devices; runtime validation remains distinct from alignment checks.

Try the workbench

The debug APK is demo/build/outputs/apk/debug/demo-debug.apk. Start with a bundled model, or choose Try the example pendulum for ready-to-run Forward and marker-IK setups. In Tools, select the setup, review Configure inputs, then Save & run; inspect the generated motion and reports in Results. The pendulum's prescribed motion and marker observations are explicitly synthetic, not recorded data. Native solver results are written separately. For your own models, import the complete project folder so relative input paths stay intact. See the GUI guide for controls and workflow limitations.

Use the library

Inside this project, depend on implementation project(':opensim'). For another application, publish the library modules to the local build repository and use the resulting Maven artifacts (not published to a public registry):

./gradlew publishAllPublicationsToLocalBuildRepository

The engine coordinate is com.saifkhichi.opensim:opensim-android:4.6.0-android.1-SNAPSHOT. Configure a Maven repository pointing to this project's build/repository. The AAR includes JNI libraries, generated Java classes, Kotlin helpers, consumer R8 rules, source provenance and third-party notices. Do not use pickFirst to silently resolve conflicting libc++_shared.so versions in a consuming app; align NDK runtimes across its native dependencies and retest.

The upstream generated Java API remains directly reachable:

import com.saifkhichi.opensim.OpenSimEngine
import org.opensim.modeling.Model

OpenSimEngine.exclusive { // Loads the engine and joins the facade's native lock.
    val model = Model(modelFile.absolutePath)
    try {
        model.setUseVisualizer(false)
        val state = model.initSystem() // borrowed state: keep the model alive
        model.realizePosition(state)
        // Model, bodies, joints, muscles, analyses, tools, tables, solvers ...
    } finally {
        model.delete()
    }
}

See Kotlin API ownership and execution and the GUI module's README for the safer session API and embedding. Native computations belong off the Android main thread. Geometry and setup files need real app-readable paths; Android content:// URIs are not native filenames. Import related files together to retain relative model/geometry/data paths.

Important boundaries

• The desktop Simbody/OpenSim visualizer is not an Android widget. The GUI module supplies its own interaction and preview; it does not launch desktop processes.
• Moco's data/model classes are wrapped, but CasADi/Ipopt optimization is not available in the initial build. Those dependencies need their own Android port and validation. A visible class must not be interpreted as a working solver.
• Desktop Python scripts, NumPy, MATLAB, Swing, external executables, and existing desktop binary plugins do not run through this package. Native plugins require compatible Android ABI builds.
• This does not establish clinical validity, accuracy, or real-time performance.

Bundled models

The workbench includes Arm26, Gait2392, Leg6Dof9Musc, Bouncing Block and Tug of War (Millard) from the supplied OpenSim 4.5 distribution. Their original .osim files and 61 shared geometry files total approximately 11.5 MB before compression. No download or desktop installation is needed to use the built APK.

Choose a gallery entry to create a checksum-verified, editable private project. Its required Geometry files and attribution accompany the model. Use Details for credits, publications and limitations. Leg6Dof9Musc is explicitly a demonstration model, not intended for research. This is a curated model collection, not all desktop tutorial datasets and ready-configured analyses. Other projects can be imported together with their input files.

The GUI offers a lightweight mesh preview using the existing native mesh loader and OpenGL ES 2, plus a diagnostic frame/marker view. Imported meshes use actual OpenSim scale factors and frame transforms. Muscle paths, textures and desktop visualizer decorations are not yet rendered. See the models module and original attribution.

Attribution

OpenSim is developed by Stanford University and its contributors. Upstream OpenSim/Simbody retain their original Apache-2.0 notices. spdlog, ezc3d, CLAPACK, f2c and bundled vendor sources retain their respective licenses. Original notices are collected into the AAR; see third-party provenance. The new adapter/workbench code is licensed under Apache-2.0.