mrpeek: a medical image viewer in the terminal

Launched as a project for the OHBM BrainHack 2020, mrpeek allows to quickly inspect 3-D and 4-D medical images without leaving the terminal.

NOTE: this currently compiles and runs on GNU/Linux & macOS systems, but not on Windows with MinGW (e.g. via MSYS2 as we would normally recommend). It may compile on cygwin or MSYS2 using their MSYS2 shell (untested). It is however perfectly possible to display images on Windows via the minTTY terminal (as provided with MSYS2) when logged onto a remote system - mrpeek only needs to be installed on the remote server, not the local system (as long as the terminal supports sixel graphics).

Demonstration

Using plot functionality with 4D data

Getting started

First, you'll need a terminal that supports sixel encoding, the format used for rendering images inline. For example:

• mlterm on Linux or macOS
• iTerm2 on macOS
• minTTY on Windows (available by default with MSYS2 installs)
• WSLtty on Windows Subsystem for Linux (WSL)

Next, install mrpeek using the precompiled executables provided in the latest release.

If that doesn't work, or you wish to get involved in the development of mrpeek, you can build it from source following these instructions:

Step 1: fetch the MRtrix3 source code

mrpeek is built an external module for MRtrix3. If you already have an existing MRtrix3 source installation, feel free to use that and skip this step.

NOTE: if you've installed MRtrix3 using our binary installers, you will still need to follow these instructions to fetch the source code and all required dependencies.

Otherwise, if all you need is to compile mrpeek, the following is probably the simplest solution: it will check out the MRtrix3 codebase and configure it for command-line only use (avoiding the Qt & OpenGL checks), without generating the MRtrix3 shared library (which will make the resulting executable easier to relocate wherever you need to).

Note that there is no need to actually build all of MRtrix3 if you don't want to: the next stage will compile what needs to be compiled for mrpeek itself.

If you're interested in getting a full installation of MRtrix3, you can follow the full instructions here.

• Make sure you have all the required dependencies. If you're only interested in compiling mrpeek, the only required dependencies are:

  • a C++11 compliant compiler
  • Python version >= 2.7
  • The zlib compression library

• Fetch the MRtrix3 repo:

  git clone https://github.com/MRtrix3/mrtrix3.git
  

• [optional] if you don't already have the Eigen3 libraries:

  git clone -b 3.3.7 https://gitlab.com/libeigen/eigen.git
  export CFLAGS="-idirafter $(pwd)/eigen"
  

• Run the MRtrix3 configure script:

  This will check for dependencies and set up the parameters of the compile process.

  cd mrtrix3/
  ./configure -noshared -nogui
  cd ..
  

  NOTE:

  • If you want a full install of MRtrix3, including the full-blown mrview application, remove the -nogui option, and make sure Qt is also installed.

  • The -noshared option will produce executables without the MRtrix3 shared library. This is not typically recommended, but is appropriate if you're only interested in compiling mrpeek itself.

Step 2: clone this repo and build it as a module:

• Clone & build:

  git clone https://github.com/MRtrix3/mrpeek.git
  cd mrpeek
  ../mrtrix3/build
  

  NOTE: that last step assumes that you've followed the instructions above. If you're using your own previous MRtrix3 source installation, you may need to edit the path to the build script in the last line above. The only requirement is that you invoke the build script of the main MRtrix3 source folder from within the mrpeek module folder (if you do this often, we recommend setting up a symbolic link to simplify the process).

• Try it out:

  bin/mrpeek /path/to/image.nii
  

• Add it to your PATH

  At this point, you may want to include the bin/ folder in your PATH.

  You can follow your system's standard procedures for this, or use the set_path convienence script provided within the main MRtrix3 source folder (documented here):

  ../mrtrix3/set_path
  

  Note this will only take effect after starting a fresh terminal.

Working on the code

• We encourage you to create your own branches, and commit very often. Once you've made a coherent set of changes, however small, commit them to your branch. This will help keep track of the evolution of the code, and is great practice anyway.

• Once you have code that more or less does what it's supposed to do, don't hesitate to push your branch to GitHub and create a pull request for it.

• We have protected the master branch so that changes (pull requests) require review before merging. This is probably not required for a small project like this, but it's a great way to ensure your changes are noticed by the other contributors and discussed if needed. It's also how things are likely to be done on any reasonable size project, so it's a good idea to get used to the process.

• Above all, have fun and experiment with the code! It's the best way to learn.