A UI for building OpenSim models
- π₯ Want to download it? Download the latest release here
- π Want to learn the basics? View the documentation online
- π Want to cite the project? See the citation section of this README
- 𧬠Want to know more about the project? See www.opensimcreator.com
- β Have a question? Go to the discussions page
- π Found a bug or want to request a feature? Post it on the issues page
OpenSim Creator (osc
) is a standalone UI for building and editing
OpenSim models. It's available
as a freestanding all-in-one installer for Windows 10,
MacOS Ventura, and Ubuntu 20 (or newer versions).
Architecturally, osc
is a C++ codebase that is directly integrated against
the OpenSim core C++ API. It otherwise only
uses lightweight open-source libraries that can easily be built from source (e.g. SDL, ImGui, and stb)
to implement the UI on all target platforms. This makes osc
fairly easy to build, integrate, and package.
osc
started development in 2021 in the Biomechanical Engineering
department at TU Delft. It is currently funded by the
Chan Zuckerberg Initiative's "Essential Open Source Software for
Science" grant (Chan Zuckerberg Initiative DAF, 2020-218896 (5022)).
Project Sponsors | |
Biomechanical Engineering at TU Delft |
Chan Zuckerberg Initiative |
You can download a binary release from the π₯ releases page. OpenSim Creator is also regularly built from source using GitHub Actions, so if you want a bleeding-edge--but unreleased--build of OpenSim Creator check the actions page (must be logged into GitHub to see artifact links).
- Download an
exe
release - Run the installer
.exe
, continue past any security warnings - Follow the familiar
next
,next
,finish
installation wizard - Run
OpenSimCreator
by typingOpenSimCreator
in your start menu, or browse toC:\Program Files\OpenSimCreator\
.
- Download a
dmg
release - Double click the
dmg
file to mount it - Drag the
osc
icon into yourApplications
directory. - Browse to the
Applications
directory inFinder
- Right-click the
osc
application, clickopen
, continue past any security warnings to runosc
for the first time- Note: you may need to do this twice, because MacOS really doesn't like unsigned binaries
- After running it the first time, you can boot it as normal (e.g.
Command+Space
,osc
,Enter
)
- Download a
deb
release - Double-click the
.deb
package and install it through your package manager UI. - Alternatively, you can install it through the command-line:
apt-get install -yf ~/Downloads/osc-X.X.X_amd64.deb
(or similar). - Once installed, the
osc
orOpenSim Creator
shortcuts should be available from your desktop, or you can browse to/opt/osc
OpenSim Creator doesn't have a central written software publication that you can cite (yet π). However, if you need to directly cite OpenSim Creator (e.g. because you think it's relevant that you built a model with it), the closest thing you can use is our DOI-ed Zenodo releases (metadata available in this repo: CITATION.cff
/codemeta.json
):
Kewley, A., Beesel, J., & Seth, A. (2024). OpenSim Creator (0.5.14). Zenodo. https://doi.org/10.5281/zenodo.13682081
If you need a general citation for the simulation/modelling technique, you can directly cite OpenSim via this paper:
Seth A, Hicks JL, Uchida TK, Habib A, Dembia CL, et al. (2018) OpenSim: Simulating musculoskeletal dynamics and neuromuscular control to study human and animal movement. PLOS Computational Biology 14(7): e1006223. https://doi.org/10.1371/journal.pcbi.1006223
If you would like to contribute to OpenSim Creator then thank you π₯°: it's people like you that make open-source awesome! See CONTRIBUTING.md for more details.
Note: The build instructions here are for general users who just want to build OSC.
Because everyone's C++ build environment is slightly different, there are no catch-all build instructions that will work for everyone. Instead, we recommend reading + running the automated build scripts, or reading some of the basic tips-and-tricks for Visual Studio or QtCreator (below).
- Get
git
:- Download+install it from https://git-scm.com/downloads
- Make sure to add it to the
PATH
. Usually, the installer asks if you want this. If it doesn't ask, then you may need to add it manually (google: "Modify windows PATH", add yourgit
install:C:\Program Files\Git\bin
) - Verify it's installed by opening a terminal (
Shift+Right-Click
->Open Powershell window here
) and rungit
- Get C++20-compatible compiler (
Visual Studio 17 2022
):- Download+install it from https://visualstudio.microsoft.com/downloads/
- Make sure to select C/C++ development in the installer wizard when it asks you what parts you would like to install
- Get
cmake
:- Download+install it from https://cmake.org/download/
- Make sure to add it to the
PATH
. Usually, the installer asks if you want this. If it doesn't ask, then you may need to add it manually (google: "Modify windows PATH", add yourcmake
install:C:\Program Files\CMake\bin
) - Verify it's installed by opening a terminal (
Shift+Right-Click
->Open Powershell window here
) and runcmake
- Get
NSIS
:- Download+install it from https://nsis.sourceforge.io/Download
- Get
python
andpip
:- Download from https://www.python.org/downloads/
- Make sure
python
andpip
are added to thePATH
(the installer usually prompts this) - Verify they are installed by opening a terminal (
Shift+Right-Click
->Open Powershell window here
) and runpython --help
andpip --help
- Build OpenSim Creator in a PowerShell terminal:
- Open a PowerShell terminal (
Shift+Right-Click
->Open Powershell window here
) - Clone
opensim-creator
:git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator
cd
into the source dir:cd opensim-creator
- Run the build script:
python .\scripts\build_windows.py
(warning: can take a long time)
- Open a PowerShell terminal (
- Done:
- The
osc-build
directory should contain the built installer
- The
- Get
brew
:- Go to https://brew.sh/ and follow installation instructions
- Get
git
:- Can be installed via
brew
:brew install git
- Can be installed via
- Get C++20-compatible compiler (e.g.
clang
via brew, or newer XCodes):- OpenSim Creator is a C++20 project, so you'll have to use a more recent XCode (>14), or
install a newer
clang
from brew (e.g.brew install clang
)
- OpenSim Creator is a C++20 project, so you'll have to use a more recent XCode (>14), or
install a newer
- Get
cmake
:- Can be installed via
brew
:brew install cmake
- Can be installed via
- Get
python
andpip
(optional: you only need this if you want to build documentation):- Can be installed via
brew
:brew install python
- Can be installed via
- Build OpenSim Creator in a terminal:
- Clone
opensim-creator
:git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator
cd
into the source dir:cd opensim-creator
- If you have multiple C++ compilers, make sure that the
CC
andCXX
environment variables point to compilers that are compatible with C++20. E.g.export CXX=$(brew --prefix llvm@15)/bin/clang++
- Run the build script:
scripts/build_mac.sh
(warning: can take a long time)
- Clone
- Done:
- The
osc-build
directory should contain the built installer
- The
- Get
git
:- Install
git
via your package manager (e.g.apt-get install git
)
- Install
- Get a C++20-compatible compiler:
- Install
g++
/clang++
via your package manager (e.g.apt-get install g++
) - They must be new enough to compile C++20 (e.g. clang >= clang-11)
- If they aren't new enough, most OSes provide a way to install a newer compiler
toolchain (e.g.
apt-get install clang-11
). You can configure which compiler is used to build OpenSim Creator by setting theCC
andCXX
environment variables. E.g.CC=clang-11 CXX=clang++-11 ./scripts/build_debian-buster.sh
- Install
- Get C++20-compatible standard library headers (usually required on Ubuntu 20):
sudo apt-get install libstdc++-10-dev
- Get
cmake
:- Install
cmake
via your package manager (e.g.apt-get install cmake
) - If your cmake is too old, build one from source, see: https://askubuntu.com/a/865294
- Install
- Get
python
andpip
(optional: you only need this if you want to build documentation):- Install
python3
andpip3
via your package manager (e.g.apt-get install python3 pip3
)
- Install
- Build OpenSim Creator in a terminal:
- Clone
opensim-creator
:git clone https://github.com/ComputationalBiomechanicsLab/opensim-creator --recursive
cd
into the source dir:cd opensim-creator
- If you have multiple C++ compilers, make sure that the
CC
andCXX
environment variables point to compilers that are compatible with C++20. E.g.export CC=clang-12
,export CXX=clang++-12
- Run the build script:
scripts/build_debian-buster.sh
- Clone
- Done:
- The
osc-build
directory should contain the built installer
- The
These are some generic tips that might be handy when setting up your own development environment.
- Run build_windows.py --skip-osc (described above) to get a complete build of OSC's dependencies.
- In Visual Studio 2020, open
opensim-creator
as a folder project - Later versions of Visual Studio (i.e. 2017+) should have in-built CMake support that automatically detects that the folder is a CMake project
- Right-click the
CMakeLists.txt
file to edit settings or build the project- You may need to set your configure command arguments to point to the dependencies install (e.g.
-DCMAKE_PREFIX_PATH=$(projectDir)/osc-dependencies-install
)
- You may need to set your configure command arguments to point to the dependencies install (e.g.
- Use the
Switch between solutions and available views
button in theSolution Explorer
hierarchy tab to switch to theCMake Targets View
- Right-click the
osc
CMake target andSet As Startup Project
, so that pressingF5
will then build+runosc.exe
- (optional): switch the solution explorer view to a
Folder View
after doing this: the CMake view is crap for developing osc - You should now be able to build+run
osc
fromVisual Studio
- To run tests, open the
Test Explorer
tab, which should list all of thegoogletest
tests in the project
- Run the appropriate (OS-dependent) buildscript (described above)
- Open QtCreator and then open the
opensim-creator
source directory as a folder - For selecting a "kit", QtCreator usually detects that
osc-build
already exists (side-effect of running the buildscript). You may need to "import existing kit/build" and then selectosc-build
, though - Once QtCreator knows your source dir (
opensim-creator/
) and build/kit (opensim-creator/osc-build
), it should be good to go