itkwidgets

Interactive Jupyter widgets to visualize images, point sets, and meshes.

Key Features:

• Visualize 2D and 3D images, point sets, and geometry, e.g. meshes, in Jupyter
• Support for
  • NumPy array images
  • itk.Image
  • Dask array images
  • vtk.vtkImageData
  • pyvista.UniformGrid
  • vtkplotter.Volume
  • pyimagej ImageJ / Fiji / ImageJ2 images
  • Additional NumPy array-like objects
  • SimpleITK.Image
  • NumPy array point sets
  • itk.PointSet
  • itk.PointBasedSpatialObject
  • vtk.vtkPolyData point sets
  • pyvista.PolyData point sets
  • itk.Mesh
  • itk.PolyLineParametricPath
  • vtk.vtkPolyData
  • vtk.vtkStructuredGrid
  • vtk.vtkUnstructuredGrid
  • vtk.vtkActor
  • vtk.vtkVolume
  • vtk.vtkAssembly
  • pyvista.PolyData
  • pyvista.StructuredGrid
  • pyvista.UnstructuredGrid
  • vtkplotter.Actor
  • vtkplotter.Assembly
  • skan.csr.Skeleton
• Exquisite volume rendering
• Tri-plane volume slicing
• Innovative, powerful opacity transfer function / window / level widget
• Label map segmentation 2D and 3D rendering
• Anisotropic voxel spacing supported
• Image line profile widget
• Compare images widget
• Widgets to select solid colors for geometry or colormaps when point data or cell data is availble
• Visualize point sets as points or spheres and interactively adjust the point size
• Combine with other ipywidgets to quickly create graphical interfaces that interactively provide insights into data algorithms

These widgets are designed to support spatial analysis with the Insight Toolkit (ITK), but they work equally well 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: 3D Label Images
• Binder: Dask Array images
• Binder: Large volumes
• Binder: NumPy array images (processed with SciPy)
• Binder: NumPy array images (processed with scikit-image)
• Binder: NumPy array for image with anisotropic spacing
• Binder: NumPy array point sets
• Binder: ITK Mesh
• Binder: ITK PointBasedSpatialObject
• Binder: skan segmentation skeleton

Recipes:

• Binder: Compare images with a checkerboard pattern
• Binder: Compare images side by side
• Binder: Examine a line profile
• Binder: Interactively explore algorithm parameters
• Binder: Record a video
• Binder: Restore a volume opacity transfer function
• Binder: Select a region of interest
• Binder: Specify camera parameters
• Binder: Specify a colormap

Installation

To install the widgets for the Jupyter Notebook with pip:

pip install itkwidgets

or with conda:

conda install -c conda-forge itkwidgets

For Jupyter Lab, additionally run:

jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-matplotlib jupyterlab-datawidgets itkwidgets

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?

Other available widgets:

• itkwidgets.line_profile: Plot an intensity line profile.
• itkwidgets.checkerboard: Compare two images in a checkerboard pattern.
• itkwidgets.compare: Compare two images side-by-side.

Using within a Docker Container

You can use itkwidgets from within a docker container with jupyterlab. To create a local docker image:

Install docker and build the docker image with:

git clone https://github.com/InsightSoftwareConsortium/itkwidgets
cd itkwidgets/docker
IMAGE=itkwidgets:0.1.0
docker build -t $IMAGE .

Then run the docker container with:

EXAMPLESDIR=`pwd`/../examples
docker run -it --rm -v $EXAMPLESDIR:/home/jovyan -p 8888:8888 itkwidgets:0.1.0

Finally, connect to your notebook at http://127.0.0.1:8888/lab

Advanced Usage

The itkwidgets are based on ipywidgets. As a consequence, widgets traits can be queried, assigned, or observed with the viewer object returned by the view function. itkwidgets 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
• 3D Label maps
• Dask Array images
• Large volumes
• ImageJ ImgLib2 images (requires conda and a local Fiji installation)
• NumPy array images (processed with SciPy)
• NumPy array images (processed with scikit-image)
• NumPy array for image with anisotropic spacing
• VTK vtkImageData
• pyvista UniformGrid
• NumPy array point sets
• ITK Mesh
• ITK PointBasedSpatialObject
• VTK vtkPolyData
• VTK vtkUnstructuredGrid
• pyvista PolyData
• pyvista StructuredGrid
• pyvista UnstructuredGrid
• pyvista LiDAR
• vtkplotter actors and volumes
• skan segmentation skeleton

or how to:

• Compares images with a checkerboard pattern
• Compares images side by side
• Examine a line profile
• Interatively explore algorithm parameters
• Record a video
• Restore a volume opacity transfer function
• Select a region of interest
• Specify camera parameters
• Specify a colormap

Troubleshooting

IOPub data rate exceeded.

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

Scrolling in JupyterLab

Cell output scrolls by default in JupyterLab. To disable scrolling, right click in the region to the left of the output and select Disable Scrolling for Outputs.

'Permission denied' during installation

If Permission denied errors occur during installation, install the Python package with user permission via:

pip install --user itkwidgets

For JupyterLab extension installation, configure JupyterLab to use your user application directory by setting the environmental variable, JUPYTERLAB_DIR:

export JUPYTERLAB_DIR=$HOME/.local/share/jupyter/lab

Check that this is picked up in the value of the Application directory reportred by:

jupyter lab path

Then, install the extension as usual:

jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-matplotlib jupyterlab-datawidgets itkwidgets

Hacking

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

git clone https://github.com/InsightSoftwareConsortium/itkwidgets.git
cd itkwidgets
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. In one terminal, start Jupyter:

cd itkwidgets
jupyter notebook

In another terminal, put Webpack in watch mode to rebuild any Javascript changes when you save a Javascript file:

cd itkwidgets
npm run watch

If Python code is changed, restart the kernel to see the changes. If Javascript code is changed, reload the page after to Webpack has finished building.

To develop for Jupyter Lab, additionally run:

jupyter labextension install @jupyter-widgets/jupyterlab-manager jupyter-matplotlib jupyterlab-datawidgets jupyter-webrtc
jupyter labextension install ./js
jupyter lab --watch

Note

Historical note: this project was previously named itk-jupyter-widgets, but it was renamed to itkwidgets to be consistent with the package name.

Warning

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