ROI Manager

API Reference

Manage and annotate ROIs


The ROI Manager has a manual mode, to draw ROIs manually, and a CNMF(E) mode where ROIs can be imported from CNMF(E) outputs.

See also



You cannot combine manual and CNMF(E) ROIs in the same sample.

The ImageJ ROI import uses the read-roi package by Hadrien Mary

Video Tutorial






Add ROI button

Add Polygon ROI (Manual mode)

Right click this button to add an elliptical ROI

Show all

Show all ROIs in the viewer

Live plot

Live update of the curve plot with changes (Manual mode)


Plot the curves (Manual mode)

Import from ImageJ

Import ROIs from an ImageJ ROIs zip file (Manual mode). Freehand ROIs are downsampled by 5.

Switch to manual …

Switch to Manual mode. Clears CNMF(E) ROIs.

ROIs list

Color-coded list of ROIs.

Left click to highlight the ROI in the viewer
Right click to show the context menu allowing you to delete the selected ROI

Tags list

List of tags for the selected ROI

Add Tag to ROI Def…

Set the tag for the current selection in the Tags list

Set ROI Tag

Click to set the tag, or just press return in the text entry above


It is generally advisable to keep your ROI tags short with lowercase letters. When sharing your project you can provide a mapping for all your keys. This helps maintain consistency throughout your project and makes the data more readable.


When using 3D data, the ROIs are colored randomly along the list (not linearly as shown in the image). If you want to set the colors linearly call this in the Viewer Console: get_workEnv().roi_manager.roi_list.reindex_colormap(random_shuffle=False)


Importing several thousands of ROIs can take 15-30 minutes. You will be able to track the progress of the import in the Viewer Window’s status bar.

Keyboard shortcuts.

These only work when the ROI manager is docked within the Viewer and while you are typing in the Add Tag to ROI Definition text entry.



Page Up

Select previous ROI

Page Down

Select next ROI

Right Arrow

Play the video at high speed

Left Arrow

Play the video backwards at high speed


Go to the beginning of the video


Go to the end of the video

Manual ROI Mode

When you click the “Add ROI” button to add a Manual Polygon ROI, a new rectangular ROI will be add in the top left corner of the image. You can add new vertices to this polygon by clicking on any of its edges. You can drag the vertices to change the shape of the polygon, and you can drag the entire ROI as well by clicking and dragging within the ROI region. Similarly you can reshape elliptical ROIs.

Hovering over the ROI selects it in the ROI list.


These examples can be run through the viewer console or Script editor to interact with the ROIs.

Get the back-end ROI Manager, see ROI Manager APIs

>>> get_workEnv().roi_manager

<mesmerize.viewer.modules.roi_manager_modules.managers.ManagerCNMFROI object at 0x7f01b8780668>``

Get the ROI List, see ROIList API

>>> get_workEnv().roi_manager.roi_list

[<mesmerize.viewer.modules.roi_manager_modules.roi_types.CNMFROI object at 0x7f01bc78b278>, <mesmerize.viewer.modules.roi_manager_modules.roi_types.CNMFROI object at 0x7f01bc817630>, <mesmerize.viewer.modules.roi_manager_modules.roi_types.CNMFROI object at 0x7f01bc817668>, <mesmerize.viewer.modules.roi_manager_modules.roi_types.CNMFROI object at 0x7f01bc7c5438>, <mesmerize.viewer.modules.roi_manager_modules.roi_types.CNMFROI object at 0x7f01bc7c5208>]

Work with an ROI object, see ROI Type APIs

# Get the curve data of an ROI
>>> get_workEnv().roi_manager.roi_list[3].curve_data

(array([   0,    1,    2, ..., 2995, 2996, 2997]), array([ -207.00168389,  -161.78229208,  -157.62522988, ..., -1017.73174502,
   -1030.27047731, -1042.26989668]))

# Get the tags of an ROI
>>> get_workEnv().roi_manager.roi_list[2].get_all_tags()

{'anatomical_location': 'tail', 'cell_name': 'dcen', 'morphology': 'untagged'}

# Get a single tag
>>> get_workEnv().roi_manager.roi_list[2].get_tag('cell_name')