stackview¶

Interactive image stack viewing in jupyter notebooks based on ipycanvas and ipywidgets.

Usage¶

You can use stackview from within jupyter notebooks as shown below.

Starting point is a 3D image dataset provided as numpy array.

In [1]:

import stackview
stackview.__version__

Out[1]:

'0.7.1'

In [2]:

import numpy as np
from skimage.io import imread
from skimage.filters import gaussian

In [3]:

image = imread('https://github.com/haesleinhuepf/stackview/blob/main/docs/data/Haase_MRT_tfl3d1.tif?raw=true', plugin='tifffile')

Slice¶

You can then view it slice-by-slice:

In [4]:

image[:3].shape

Out[4]:

(3, 160, 160)

In [5]:

stackview.slice(image[:3], continuous_update=True)

Out[5]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), IntSlider(value=1, desc…

Insight¶

You can also get a static view using a maximum-intensity projection with additional information.

In [6]:

stackview.insight(image)

Out[6]:

shape	(120, 160, 160)
dtype	uint16
size	5.9 MB
min	0
max	65535

Annotate¶

To draw label images, use annotate.

In [7]:

import numpy as np
labels = np.zeros(image.shape).astype(np.uint32)

stackview.annotate(image, labels)

Out[7]:

VBox(children=(HBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), VBox(chi…

Picker¶

To read the intensity of pixels where the mouse is moving, use the picker.

In [8]:

stackview.picker(image, continuous_update=True)

Out[8]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), IntSlider(value=60, des…

Orthogonal¶

Orthogonal views are also available:

In [9]:

stackview.orthogonal(image, continuous_update=True)

Out[9]:

HBox(children=(VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), IntSlide…

Curtain¶

For visualization of an original image in combination with a processed version, a curtain view may be helpful:

In [10]:

modified_image = image.max() - image

In [11]:

stackview.curtain(image, modified_image, continuous_update=True)

Out[11]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), IntSlider(value=60, des…

One can also use the curtain to visualize semantic segmentation results as label images.

In [12]:

labels = (image > 5000)*1 + (image > 15000)*1 + (image > 30000)*1

In [13]:

stackview.curtain(image, labels, continuous_update=True)

Out[13]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), IntSlider(value=60, des…

The curtain can also be partially transparent using the alpha value.

In [14]:

stackview.curtain(image, labels, continuous_update=True, alpha=0.3)

Out[14]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=160, width=160),)),)), IntSlider(value=60, des…

The curtain also works with 2D data

In [15]:

slice_image = imread('https://github.com/haesleinhuepf/stackview/blob/main/docs/data/blobs.tif?raw=true', plugin='tifffile')

In [16]:

from skimage.filters import threshold_otsu
binary = (slice_image > threshold_otsu(slice_image))

In [17]:

binary.shape, slice_image.shape

Out[17]:

((254, 256), (254, 256))

In [18]:

stackview.curtain(slice_image, binary, continuous_update=True)

Out[18]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=254, width=256),)),)), IntSlider(value=127, de…

Also label images are supported. Images are shown as labels in case their pixel type is (unsigned) integer 32-bit or 32-bit.

In [19]:

from skimage.measure import label
labels = label(binary)

In [20]:

stackview.curtain(slice_image, labels, continuous_update=True)

Out[20]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=254, width=256),)),)), IntSlider(value=127, de…

Side-by-side¶

A side-by-side view of two stacks is also available. It might be useful for colocalization visualization or showing subsequent time points of a timelapse.

In [21]:

image_stack = imread('https://github.com/haesleinhuepf/stackview/blob/main/docs/data/CalibZAPWfixed_000154_max.tif?raw=true', plugin='tifffile').swapaxes(1,2)

In [22]:

stackview.side_by_side(image_stack[1:], image_stack[:-1], continuous_update=True, display_width=300)

Out[22]:

VBox(children=(HBox(children=(HBox(children=(VBox(children=(ImageWidget(height=235, width=389),)),)), HBox(chi…

In [23]:

labels_stack = np.asarray([label(image > 100) for image in image_stack])

In [24]:

stackview.side_by_side(image_stack, labels_stack, continuous_update=True, display_width=300)

Out[24]:

VBox(children=(HBox(children=(HBox(children=(VBox(children=(ImageWidget(height=389, width=235),)),)), HBox(chi…

Switch¶

If there are many images you would like to inspect, you can pass them as dictionary or list to switch().

In [25]:

stackview.switch({
    "image":slice_image,
    "binary":binary,
    "labels":labels
})

Out[25]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=254, width=256),)),)), HBox(children=(Button(d…

In [26]:

stackview.switch([image_stack[1:], image_stack[:-1]])

Out[26]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=389, width=235),)),)), HBox(children=(Button(d…

In [27]:

stackview.switch([
    slice_image,
    binary,
    labels
])

Out[27]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=254, width=256),)),)), HBox(children=(Button(d…

In [28]:

hela_cells = imread("data/hela-cells.tif")
hela_cells.shape

Out[28]:

(512, 672, 3)

In [29]:

stackview.switch(
    {"lysosomes":   hela_cells[:,:,0],
     "mitochondria":hela_cells[:,:,1],
     "nuclei":      hela_cells[:,:,2]
    },
    colormap=["pure_magenta", "pure_green", "pure_blue"],
    toggleable=True
)

Out[29]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=512, width=672),)),)), HBox(children=(ToggleBu…

Crop¶

The crop widget allows to crop the image in Z,Y and X.

In [30]:

crop_widget = stackview.crop(image_stack)
crop_widget

Out[30]:

_Cropper(children=(IntRangeSlider(value=(0, 100), description='Z'), IntRangeSlider(value=(0, 389), description…

You can retrieve the range the user entered like this:

In [31]:

crop_widget.range

Out[31]:

(slice(0, 100, 1), slice(0, 389, 1), slice(0, 235, 1))

You can also get the cropped image directly.

In [32]:

crop_widget.crop()

Out[32]:

shape	(100, 389, 235)
dtype	uint8
size	8.7 MB
min	0
max	255

Interact¶

You can also use interact to explore parameters of some supported functions that process images, e.g. from scikit-image:

In [33]:

from skimage.filters.rank import maximum
stackview.interact(maximum, slice_image)

Out[33]:

VBox(children=(interactive(children=(IntSlider(value=0, description='footprint'), Output()), _dom_classes=('wi…

In [34]:

from skimage.filters import gaussian
stackview.interact(gaussian, slice_image)

Out[34]:

VBox(children=(interactive(children=(FloatSlider(value=1.0, description='sigma', max=25.0, step=1.0), Output()…

This might be interesting for custom functions executing image processing workflows.

In [35]:

from skimage.filters import gaussian, threshold_otsu, sobel
def my_custom_code(image, sigma:float = 1, show_labels: bool = True):
    sigma = abs(sigma)
    blurred_image = gaussian(image, sigma=sigma)
    binary_image = blurred_image > threshold_otsu(blurred_image)
    edge_image = sobel(binary_image)
    
    if show_labels:
        return label(binary_image)
    else:
        return edge_image * 255 + image 

stackview.interact(my_custom_code, slice_image, continuous_update=True)

Out[35]:

VBox(children=(interactive(children=(FloatSlider(value=1.0, description='sigma', max=25.0, step=1.0), Checkbox…

If you want to configure the range of a slider explicitly, you need to hand over the ipywidgets slider as default value:

In [36]:

from skimage.filters import gaussian
from ipywidgets import FloatSlider
stackview.interact(gaussian, slice_image, sigma=FloatSlider(min=0, max=100, value=15), continuous_update=True)

Out[36]:

VBox(children=(interactive(children=(FloatSlider(value=15.0, description='sigma'), Output()), _dom_classes=('w…

Assist¶

The stackview.assist() function can guide you through all imported (and supported) image processing functions.

In [37]:

stackview.assist(context=globals(), continuous_update=True)

Out[37]:

VBox(children=(Text(value='', description='Search', placeholder='Type here to search'), Dropdown(description='…

Some more tests with silly images¶

In [38]:

import numpy as np
silly_image = np.zeros((100, 100))
silly_image[:,50:] = 1
silly_image[50:] = silly_image[50:] + 2

stackview.picker(silly_image.astype(np.uint32))

Out[38]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=100, width=100),)),)), IntSlider(value=50, des…

In [39]:

silly_image = np.zeros((3, 3))
silly_image[:,1:] = 1
silly_image[1:] = silly_image[1:] + 2

stackview.picker(silly_image.astype(np.uint32), zoom_factor=20)

Out[39]:

VBox(children=(HBox(children=(VBox(children=(ImageWidget(height=60, width=60),)),)), IntSlider(value=1, descri…

In [ ]: