Viewer overview

Based on the pyqtgraph ImageView widget.

The Viewer allows you to do the following things:

  • Examine your calcium movies

  • Use modules to perform things like motion correction, CNMF(E), ROI labeling, and stimulus mapping. See their respective guides for details.

  • You can also make modifications to an existing Sample in your project by opening it in the Viewer. See Modify Sample and Overwrite guide.

Video Tutorial

This tutorial shows how to create a New Project, open images in the Viewer, use the Stimulus Mapping module and perform Caiman motion correction



To access Viewer modules choose the module you want to run from the Modules menu at the top. All modules, except the Batch Manager, are small floating windows which you can dock into the Viewer by dragging them to an edge of the viewer.

3D data

When viewing 3D data a slider on the left allows you to move through the z axis.


The image stack shown above is from Martin Haesemeyer’s dataset from the following paper:

Haesemeyer M, Robson DN, Li JM, Schier AF, Engert F. A Brain-wide Circuit Model of Heat-Evoked Swimming Behavior in Larval Zebrafish. Neuron. 2018;98(4):817-831.e6. doi:10.1016/j.neuron.2018.04.013

Work Environment

Everything in the viewer is stored in a Work Environment object. The main data attributes of the viewer work environment are outlined below.




ImgData object containing the Image Sequence and meta data from the imaging source


The back-end ROI Manager that is currently in use


SampleID, if opened from a project Sample


Stimulus maps, if any are defined


History log, currently used for logging caiman motion correction, CNMF and CNMFE history.


If opened from a project Sample, it refers to the ImgUUID

You can view everything in the current work environment by going to View -> Work Environment Editor. You cannot edit through this GUI at this time.


You can interact directly with the work environment using the console.





Instance of ViewerUtils. Use this to interact with the viewer.


List all available modules (includes default and any available plugins/custom modules)


Use for creating new instances of ViewerWorkEnv


Use for creating new instances of ImgData


Get the current viewer work environment (instance of ViewerWorkEnv)


Get the current image sequence (returns current ViewerWorkEnv.imgdata.seq). If the data are 3D it returns the current plane only.


Get the current meta data


Pass the name of a module as a string. Returns that module if it is available.


Get the batch manager.


Update the viewer GUI with the viewer work environment (vi.viewer.workEnv)


Clear the current work envionment, cleanup the GUI and free the RAM

Video Tutorial


These examples can be run in the Viewer Console.

Working with meta data

# view meta data
>>> get_meta()

{'origin': 'AwesomeImager', 'version': '4107ff58a0c3d4d5d3c15c3d6a69f8798a20e3de', 'fps': 10.0, 'date': '20190426_152034', 'vmin': 323, 'vmax': 1529, 'orig_meta': {'source': 'AwesomeImager', 'version': '4107ff58a0c3d4d5d3c15c3d6a69f8798a20e3de', 'level_min': 323, 'stims': {}, 'time': '152034', 'date': '20190426', 'framerate': 10.0, 'level_max': 1529}}

# manually set meta data entries
>>> get_meta()['fps'] = 30.0

Open image

Use the Viewer Core API to open any arbitrary image

This example loads an image stored using, but this is applicable to images stored in any format that can eventually be represented as a numpy array in python. For example, you could also load image files stored in HDF5 format and load the numpy array that represents your image sequence.

 1import numpy as np
 3# clear the viewer work environment
 6a = np.load('/path_to_image.npy')
 8# check what the axes order is
11# (1000, 512, 512) # for example
12# looks like this is in [t, x, y]
13# this can be transposed so we get [x, y, t]
14# ImgData takes either [x, y, t] or [x, y, t, z] axes order
16# Define a meta data dict
17meta = \
18    {
19        "origin":      "Tutorial example",
20        "fps":         10.0,
21        "date":        "20200629_171823",
22        "scanner_pos": [0, 1, 2, 3, 4, 5, 6]
23    }
25# Create ImgData instance
26imgdata = ImgData(a.T, meta)  # use a.T to get [x, y, t]
28# Create a work environment instance
29work_env = ViewerWorkEnv(imgdata)
31# Set the current Viewer Work Environment from this new instance
32vi.viewer.workEnv = work_env
34# Update the viewer with the new work environment
35# this MUST be run whenever you replace the viewer work environment (the previous line)

Image data

Image sequences are simply numpy arrays. For example extract the image sequence between frame 1000 and 2000.

 1# Get the current image sequence
 2seq = get_image()
 4# Trim the image sequence
 5trim = seq[:, :, 1000:2000]
 7# Set the viewer work environment image sequence to the trim one
 8vi.viewer.workEnv.imgdata.seq = trim
10# Update the GUI with the new work environment

View analysis log

View the analysis log, such as batch manager processing history.

>>> get_workEnv().history_trace

[{'caiman_motion_correction': {'max_shifts_x': 32, 'max_shifts_y': 32, 'iters_rigid': 1, 'name_rigid': 'Does not matter', 'max_dev': 20, 'strides': 196, 'overlaps': 98, 'upsample': 4, 'name_elas': 'a1_t2', 'output_bit_depth': 'Do not convert', 'bord_px': 5}}, {'cnmfe': {'Input': 'Current Work Environment', 'frate': 10.0, 'gSig': 10, 'bord_px': 5, 'min_corr': 0.9600000000000001, 'min_pnr': 10, 'min_SNR': 1, 'r_values_min': 0.7, 'decay_time': 2, 'rf': 80, 'stride': 40, 'gnb': 8, 'nb_patch': 8, 'k': 8, 'name_corr_pnr': 'a8_t1', 'name_cnmfe': 'a1_t2', 'do_corr_pnr': False, 'do_cnmfe': True}}, {'cnmfe': {'Input': 'Current Work Environment', 'frate': 10.0, 'gSig': 10, 'bord_px': 5, 'min_corr': 0.9600000000000001, 'min_pnr': 14, 'min_SNR': 1, 'r_values_min': 0.7, 'decay_time': 4, 'rf': 80, 'stride': 40, 'gnb': 8, 'nb_patch': 8, 'k': 8, 'name_corr_pnr': '', 'name_cnmfe': 'a1_t2', 'do_corr_pnr': False, 'do_cnmfe': True}}]

Running scripts

You can use the Script Editor to run scripts in the Viewer console for automating tasks such as batch creation. It basically allows you to use the viewer console more conveniently with a text editor. The execution environment of the viewer console and script editor are identical.

Some example are provided for caiman modules and stimulus mapping.