itkwidgets 0.13.0

Jupyter widgets to visualize images in 2D and 3D

Interactive Jupyter widgets to visualize images in 2D and 3D.

These widgets are designed to support image analysis with the Insight Toolkit (ITK), but they also work with other spatial analysis tools in the scientific Python ecosystem.

These widgets are built on itk.js and vtk.js.

Examples on Binder

Data types:

• Binder: 2D ITK Images

• Binder: 3D ITK Images

• Binder: Dask Array images

• Binder: NumPy array images (processed with SciPy)

• Binder: NumPy array images (processed with scikit-image)

Tasks:

• Binder: Record a video

• Binder: Select a region of interest

• Binder: Specify a colormap

Installation

To install the widgets for the Jupyter Notebook:

pip install itkwidgets

For Jupyter Lab, additionally run:

jupyter labextension install @jupyter-widgets/jupyterlab-manager itk-jupyter-widgets

Usage

In Jupyter, import the view function:

from itkwidgets import view

Then, call the view function at the end of a cell, passing in the image to examine:

view(image)

For information on additional options, see the view function docstring:

view?

Advanced Usage

The itk-jupyter-widgets are based on ipywidgets. As a consequence, widgets traits can be queried, assigned, or observed with the viewer object returned by the view function. itk-jupyter-widgets can be combined with other ipywidgets to quickly explore algorithm parameters, create graphical interfaces, or create data visualization dashboards.

Mouse Controls

Left click + drag

Rotate

Right click + drag or shift + left click + drag

Pan

Mouse wheel or control + left click + drag or pinch

Zoom

Alt + left click + drag left-right

Change color transfer function window

Shift + left click + drag top-bottom

Change color transfer function level

Shift + alt + left click + drag top-bottom

Change primary Gaussian volume opacity transfer function magnitude

Keyboard Shortcuts

Keyboard shortcuts take effect when the mouse is positioned inside the viewer. All shortcuts are prefixed with Alt+. Corresponding keys for the Dvorak keyboard layout have the same effect.

Alt + 1

X-plane mode

Alt + 2

Y-plane mode

Alt + 3

Z-plane mode

Alt + 4

Volume rendering mode

Alt + q

Toggle user interface

Alt + w

Toggle region of interest (ROI) selection widget

Alt + e

Reset ROI

Alt + r

Reset camera

Alt + s

Toggle slicing planes in volume rendering mode

Alt + f

Toggle fullscreen

Examples

After installation, try the following examples that demonstrate how to visualize:

• 2D ITK Images

• 3D ITK Images

• Dask Array images

• ImageJ ImgLib2 images (requires conda and a local Fiji installation)

• NumPy array images (processed with SciPy)

• NumPy array images (processed with scikit-image)

• VTK vtkImageData

or how to:

• Record a video

• Select a region of interest

• Specify a colormap

Troubleshooting

If you experience the notebook warning:

IOPub data rate exceeded.
The notebook server will temporarily stop sending output
to the client in order to avoid crashing it.
To change this limit, set the config variable
`--NotebookApp.iopub_data_rate_limit`.

Set the notebook configuration value:

jupyter notebook --NotebookApp.iopub_data_rate_limit=1e12

Hacking

Participation is welcome! For a development installation (requires Node.js):

git clone https://github.com/InsightSoftwareConsortium/itk-jupyter-widgets.git
cd itk-jupyter-widgets
python -m pip install -r requirements-dev.txt -r requirements.txt
python -m pip install -e .
jupyter nbextension install --py --symlink --sys-prefix itkwidgets
jupyter nbextension enable --py --sys-prefix itkwidgets
jupyter nbextension enable --py --sys-prefix widgetsnbextension
python -m pytest

The above commands will setup your system for development with the Jupyter Notebook. To develop for Jupyter Lab, additionally run:

jupyter labextension install @jupyter-widgets/jupyterlab-manager
jupyter labextension install ./js

Warning

This project is under active development. Its API and behavior may change at any time. We mean it.