iMSTK - Interactive Medical Simulation Toolkit

• About
  • Overview
  • Participants
  • Licensing
• Resources
  • Documentation
  • Discourse
  • Issue tracker
• Prerequisites
• Getting started with iMSTK
  • Getting the source code
  • Setting up your SSH key
  • Building iMSTK

About

Overview

iMSTK is a C++ based free & open-source toolkit that aids rapid prototyping of real-time multi-modal surgical simulation scenarios. Surgical simulation scenarios involve algorithms from areas such as haptics, advanced rendering, computational geometry, computational mechanics, virtual reality and parallel computing. iMSTK employs a highly modular and extensible design to enable the use of libraries and codes from these areas in a given application thereby reducing the development time.

Participants

• Kitware, Inc.
• CeMSIM-Rensselaer Polytechnic Institute
• University of Central Arkansas

Funding support:

This project is supported in part by the following grants 9R44OD018334, 1R44EB019802, 1R44AR075481 , 1R01EB025247, 2R44DK115332

Disclaimer: The content is solely the responsibility of the authors and does not necessarily represent the official views of the NIH and its institutes.

Licensing

iMSTK is licensed under Apache 2.0

Resources

Documentation

Click here for detailed documentation.

Discourse

The iMSTK Users and Developers can post questions and discuss relevant topics at the Discourse.

Issue-tracker

Designed more specifically for developers, the issue tracker allows developers to list and discuss issues & enhancements:

https://gitlab.kitware.com/iMSTK/iMSTK/issues

Assign labels to the issues. The description of each label can be found HERE.

bug compilation critical enhancement optimization clean up refactor testcase visualization mechanics device documentation support discussion

Prerequisites

• Git
• Git LFS
• CMake 3.15 or higher

On Linux:

sudo apt-get install build-essential libgl1-mesa-dev libxt-dev libusb-1.0-0-dev git-lfs

Getting started with iMSTK

1. Getting the source code

To be able to contribute back to the iMSTK project, the preferred way is to use Git for code version control. You can use the following command in the terminal for Linux/macOS, or in Git Bash for Windows.

git clone git@gitlab.kitware.com:iMSTK/iMSTK.git

2. Setting up your SSH key

The build process will check out external dependency sources with the SSH protocol to avoid manually entering credentials during the build process. To allow this, make sure you set up your ssh key in your profile HERE. You can find documentation on how to generate and retrieve your public ssh key HERE.

3. Building iMSTK

We use CMake to configure the project on every platform. See how to run it HERE.

• On Linux/macOS

Type the following commands from the same location you cloned the code. This will configure the build in a directory adjacent to the source directory. To easily change some configuration variables like CMAKE_BUILD_TYPE, use ccmake instead of cmake.

mkdir iMSTK-build
cd iMSTK-build
cmake ../iMSTK #/path/to/source/directory
make -j4 #to build using 4 cores

You can also use Ninja for a faster build instead of Unix Makefiles. To do so, configure the cmake project with -GNinja:

cmake -GNinja ../iMSTK
ninja

This will checkout, build and link all iMSTK dependencies. When making changes to iMSTK base source code, you can then build from the Innerbuild directory.

• On Windows

Run CMake-GUI and follow the directions described HERE. You will have to choose which version of Visual Studio you'd like to use when configuring the project, make sure to select Microsoft Visual Studio C++ 15 2017 or 2019. CMake will generate a iMSTK.sln solution file for Visual Studio at the top level. Open this file and build all targets, which will checkout, build and link all iMSTK dependencies. When making changes to iMSTK base source code, you can then build from the iMSTK.sln solution file located in the Innerbuild directory. If you would like to build on multiple cores add /MP[N] to CMAKE_CXX_FLAGS in CMake-GUI, where N is optional representing the number of cores (without N supplied, the build will use as many cores as available on the device). If you check out the unit tests or the examples make sure to run git install lfs to make sure that git lfs is installed.

• PhysX Support

Please note, we are currently deprecating PhysX support, by default PhysX will be OFF but can be turned on via iMSTK_USE_PHYSX in the CMAKE configuration

PhysX supports multiple build configurations, designed for different stages of development and deployment.

• The DEBUG build can be useful for error analysis, but contains asserts used for SDK development which some customers may find too intrusive for daily use. Optimizations are turned off for this configuration.
• The CHECKED build contains code to detect invalid parameters, API race conditions, and other incorrect uses of the API which might otherwise cause mysterious crashes or failures in simulation.
• The PROFILE build omits the checks, but still has PVD and memory instrumentation.
• The RELEASE build is built for minimal footprint and maximum speed. It omits most checks and instrumentation.

Simulation works the same way in all of them, and all are compiled with high optimization levels (except debug configuration).

Due to the fluid nature of development and the need to easily switch between these different configurations, the iMSTK superbuild will build ALL of these configurations, regardless of the provided BUILD_TYPE. The iMSTK superbuild provides a CMake variable iMSTK_PHYSX_CONFIGURATION for you to specify the PhysX configuration it will use when building both Release and RelWithDebugInfo configurations Using this variable, you may select RELEASE, CHECKED, or PROFILE, and iMSTK will link to those libraries. Debug iMSTK builds will always link to the DEBUG PhysX libraries. By default, RELEASE libraries will be used.

Note We strongly recommend that you use the CHECKED build if you are developing new PhysX functionality in iMSTK.

Once the superbuild is complete, you may also switch the PhysX library of the Innerbuild by selecting the desired configuration via the PHYSX_CONFIGURATION variable and regenerating the InnerBuild via CMake.

• Phantom Omni Support

To support the Geomagic Touch (formerly Sensable Phantom Omni) haptic device, follow the steps below:

1. Install the OpenHaptics SDK as well as the device drivers:
   • for Windows
   • for Linux
2. Reboot your system.
3. Configure your CMake project with the variable iMSTK_USE_OpenHaptics set to ON.
4. After configuration, the CMake variable OPENHAPTICS_ROOT_DIR should be set to the OpenHaptics path on your system.

• VRPN Support

The VRPNDeviceModule enables access to a large number devices supported by VRPN. The VRPNDeviceModule expects a vrpn_server to be running. The iMSTK superbuild builds and installs a server with some default settings but if you want to configure a specific server it might be easier to separately build a server. The file CMake\External\External_VRPN.cmake shows how to pass configuration into VRPN in case you want to modify the modules enabled and disabled by the build

The vrpn.cfg that is installed by default doesn't have any devices enabled, before use you will need to uncomment the devices that you would like to use. If you use the one inside the iMSTK install directory please note that it will be overwritten every time the superbuild is run.

Currently iMSTK supports VRPN Analog, Button and Tracker devices. Future support will depend on user demand.

• Offscreen Rendering

To render without the usage of a GPU or without the usage of a screen on linux (or WSL), iMSTK's VTK renderer may be built with OSMesa.

1. Install osmesa libraries via:

sudo apt install mesa-common-dev libosmesa6-dev libglu1-mesa-dev`

2. Set iMSTK_USE_VTK_OSMESA to ON
3. Proceed to build iMSTK