pyscivis 0.9.2

A visualization tool for ISMRMRD files. Can be used standalone or embedded into Jupyter Notebooks.

pyscivis

pyscivis is a Python package for visualizing ismrmrd/mrd-files. You can run it as both a standalone application or embed it into a jupyter notebook.

Note that this package is still under heavy development. If you encounter any bugs please open an issue where you include the exception, the steps to reproduce the bug and (if possible) the data you tried to visualize!

If you do not have ismrmrd-files but still want to play around with this application, I suggest using ismrmrd-files (.h5) from this repo: ismrmrdviewer.

Note

• If selecting the BoxEditTool (to draw ROIs) you need to hold shift while dragging OR double click, then drag to draw the box: Demo

Table of contents

1. Installation
   1. Production
   2. Development
2. Usage
   1. Standalone
   2. Notebook
   3. Server
3. Configuration
4. Writing Extensions
5. Creating and Compiling custom models
   1. Difference between "start up" and pre-compiled models
6. Building the documentation

Installation

Production

Use the package manager pip to install pyscivis.

> pip install pyscivis

Development

Clone this repository

> git clone https://gitlab.com/chi-imrt/pyscivis/pyscivis.git

and install dev-dependencies

> pip install -r requirements/test.txt

or to run setup.py locally

> pip install -e .[testing]

Usage

Standalone

After installation simply run this in your terminal:

> pyscivis

This will show you possible command-line arguments:

> pyscivis --help

usage: pyscivis [-h] [-f FILE] [-n] [-c]

pyscivis

optional arguments:
  -h, --help            show this help message and exit
  -f PATH, --file PATH, --filename PATH
                        Path of file to be initially displayed
  -n, --noselector      Disable the file selector widget
  -c, --configfile      Print the path of the configuration file
  -p PORT, --port PORT  The port the bokeh application should use. Bokeh-default: 5006
  -s [SHARED_DIR], --server [SHARED_DIR]
                        Run the application in server-mode. The optional parameter sets the root directory containing
                        accessible files. Default for SHARED_DIR is the current working directory
  -w HOST[:PORT], --allow-websocket-origin HOST[:PORT]
                        The bokeh server will only accept connections coming from the specified URL. Can be specified
                        multiple times to allow multiple origins. Default: localhost:5006

Notebook

Please check the notebook-example in the examples folder for an introduction on how to use pyscivis in conjunction with jupyter notebook.

Be aware that if you use the Notebook in a dockerized environment you will need to make sure the bokeh-server ports (as specified in the config) are forwarded and you call nb.enable with the docker keyword, i.e., nb.enable(docker=True)

Server

It is possible to deploy this application using web frameworks like flask. An example snippet to run a flask server is located here.

This script will fetch a session from the currently running pyscivis at the specified port. To run pyscivis in server-mode use

> pyscivis --server SHARED_DIR --allow-websocket-origin=URL_OF_SERVING_WEBSITE:PORT

Note that, if the optional argument SHARED_DIR is omitted, the current working directory will be browsable by the user. If the bokeh-application should run on a different port, specify --port YOUR_PORT.

If reverse proxies are used certain modifications like using relative URLs might be necessary. Check the bokeh docs for further information on how to set up a server with a bokeh-app.

Configuration

There are a few parameters that you can tune to your liking. The configuration file is located in "src/pyscivis".

If you have trouble finding it, consider using

> pyscivis --configfile

which will print a path to your configuration file.

Writing Extensions for other files

Currently only ismrmrd-files and (some) types of images are supported. If you wish to support other files you will have to implement a custom extension.

The procedere is described here.

Creating and Compiling custom models

Bokeh supports the usage of custom models. This allows the usage of more specialized HTML+JS constructs in a bokeh-supported way.

However, these models have to be compiled on every start of the bokeh server (be it standalone or in the notebook), which can introduce huge delays. To avoid this, pyscivis ships with all custom models pre-compiled.

If you wish to modify existing models or create new ones, study pyscivis's models and read the docs. To manually re-compile them, go to src/pyscivis and run > bokeh build which will require external dependencies like npm. See this manual for further explanation.

Note: Models that get compiled on every startup have a different structure compared to the ones that you pre-compile. For the first, simply read the docs linked above. For the latter, look at pyscivis's models AND read this awesome tutorial from Marc Skov Madsen AND specifically this minimal example carefully. Even though it's written for the higher-level bokeh wrapper Awesome Panel, it holds true for pre-compiling bokeh models.

Difference between "start up" and pre-compiled models.

The following table shows all structural differences between "start up" and pre-compiled files to allow an easier entry point to writing models and pre-compiling them. TS means it's related to the typescript-files, PY to python files.

	start up	pre-compiled
"library import" (TS)	plain "bokeh"	"@bokehjs"*
__implementation__-dunder (PY)	necessary	forbidden
static __module__ = "pyscivis.visualizer.models.mymodel" (TS)	forbidden	necessary

Note: All other things have been explained in great detail in the documentation above (including the links).

* Name can vary depending on what you write into your tsconfig.json.

Building the documentation

The documentation is written with Google-style docstrings. This allows the documentation to be build using either doxygen+doxypypy or sphinx.

To build the documentation using doxygen follow these steps:

0. Installing dependencies

   0. Install doxygen from the doxygen website, make sure it's in your path if you are using windows
   1. Install doxypypy from the repo (not pypi as it's outdated)

   > pip install git+https://github.com/Feneric/doxypypy
   

1. Navigate to the doxygen folder of this repo

   > cd doxygen
   

2. Run the script appropriate for your OS, e.g. for Unix systems do:

   > doxygen Doxyfile_unix
   

3. Done. Check the directory html for the output

Note: Depending on your Python version the 2nd step might fail (errors in output log), in this case add this snippet to your local doxypypy version.