neuroinformatics-unit · niksirbi · Mar 23, 2026 · Jun 18, 2025 · Jun 18, 2025 · Jun 18, 2025
diff --git a/docs/make_api.py b/docs/make_api.py
@@ -25,6 +25,7 @@
 EXCLUDE_MODULES = {
     "movement.cli_entrypoint",
     "movement.napari.loader_widgets",
+    "movement.napari.regions_widget",
     "movement.napari.meta_widget",
 }
 

diff --git a/docs/source/_static/napari_bboxes_layer.png b/docs/source/_static/napari_bboxes_layer.png
diff --git a/docs/source/_static/napari_bboxes_layers.png b/docs/source/_static/napari_bboxes_layers.png
diff --git a/docs/source/_static/napari_drawing_regions.png b/docs/source/_static/napari_drawing_regions.png
diff --git a/docs/source/_static/napari_new_region_layer.png b/docs/source/_static/napari_new_region_layer.png
diff --git a/docs/source/_static/napari_plugin_data_tracks.png b/docs/source/_static/napari_plugin_data_tracks.png
diff --git a/docs/source/_static/napari_plugin_video_slider.png b/docs/source/_static/napari_plugin_video_slider.png
diff --git a/docs/source/_static/napari_points_layer_tooltip.png b/docs/source/_static/napari_points_layer_tooltip.png
diff --git a/docs/source/_static/napari_points_tooltip.png b/docs/source/_static/napari_points_tooltip.png
diff --git a/docs/source/_static/napari_poses_layers.png b/docs/source/_static/napari_poses_layers.png
diff --git a/docs/source/_static/napari_tracks_layer_head_length.png b/docs/source/_static/napari_tracks_layer_head_length.png
diff --git a/docs/source/_static/napari_tracks_sliders.png b/docs/source/_static/napari_tracks_sliders.png
diff --git a/...ce/_static/napari_plugin_video_reader.png → docs/source/_static/napari_video_reader.png b/...ce/_static/napari_plugin_video_reader.png → docs/source/_static/napari_video_reader.png
diff --git a/docs/source/_static/napari_video_slider.png b/docs/source/_static/napari_video_slider.png
diff --git a/docs/source/community/contributing.md b/docs/source/community/contributing.md
@@ -471,6 +471,76 @@ SourceSoftware: TypeAlias = Literal[
 ]
 ```
 
+### Developing the napari plugin
+
+The `movement` plugin for `napari` is built following the
+[napari plugin guide](napari:plugins/building_a_plugin/index.html).
+All widgets subclass `qtpy.QtWidgets.QWidget` (see the
+[napari guide on widgets](napari:plugins/building_a_plugin/guides.html)).
+
+The plugin lives in [`movement.napari`](movement-github:tree/main/movement/napari)
+and is structured as follows:
+
+- `movement.napari.meta_widget`: the top-level
+  container widget registered as the `napari` plugin entry point,
+  which brings together all other subwidgets:
+  - `movement.napari.loader_widgets`: a Qt form widget for
+    loading tracked datasets from supported file formats as
+    points, tracks and boxes.
+  - `movement.napari.regions_widget`: a Qt table widget for managing named
+    regions of interest drawn as `napari` shapes layers.
+    See the next section for more details on this widget's architecture.
+- {mod}`movement.napari.layer_styles`: dataclasses that encapsulate visual
+  properties for each layer type.
+- {mod}`movement.napari.convert`: functions for converting `movement`
+  datasets into the NumPy arrays and properties DataFrames
+  that `napari` layer constructors expect.
+
+#### Qt Model/View architecture
+
+`movement.napari.regions_widget` follows
+[Qt's Model/View pattern](qt6:model-view-programming.html)
+to separate the data (what is stored) from the display (how it is shown).
+Understanding this pattern is helpful before making changes to this module,
+and for creating new widgets that follow the same design principles.
+
+The three components are:
+
+- `RegionsTableModel` (subclasses
+  [`QAbstractTableModel`](qt6:qabstracttablemodel.html)):
+  wraps a `napari` [shapes layer](napari:howtos/layers/shapes.html) and
+  exposes its data to Qt (i.e., region names from `layer.properties["name"]`
+  and shape types). It listens to `napari` layer
+  [events](napari:guides/events_reference.html) and emits Qt signals
+  when the data changes.
+- `RegionsTableView` (subclasses [`QTableView`](qt6:qtableview.html)):
+  renders the model's data as a table and handles user interactions
+  (e.g. row selection, inline name editing). Keeps table row selection
+  in sync with `napari`'s current shape selection.
+- `RegionsWidget`: connects the table model and table view. It manages
+  layer selection, creates and links models to views, and handles layer
+  lifecycle events.
+
+Data flows in both directions:
+
+```
+napari shapes layer <-> RegionsTableModel <-> RegionsTableView <-> User
+```
+
+:::{dropdown} Preventing circular updates in bidirectional syncs
+:color: success
+:icon: light-bulb
+
+Bidirectional syncing between `napari` and the Qt table can cause circular
+updates. For example, selecting a `napari` shape selects the corresponding
+table row, which would then re-trigger shape selection.
+
+Guard flags such as `_syncing_row_selection` and `_syncing_layer_selection`
+break this cycle: while a sync is in progress, the corresponding flag is set
+to `True` and any events that would re-trigger it are ignored. Preserve this
+pattern when adding new two-way sync logic.
+:::
+
 ### Continuous integration
 All pushes and pull requests will be built by [GitHub actions](github-docs:actions).
 This will usually include linting, testing and deployment.

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -251,6 +251,7 @@
     "uv": "https://docs.astral.sh/uv/{{path}}#{{fragment}}",
     "attrs": "https://www.attrs.org/en/stable/{{path}}#{{fragment}}",
     "pytest-benchmark": "https://pytest-benchmark.readthedocs.io/en/latest/{{path}}#{{fragment}}",
+    "qt6": "https://doc.qt.io/qt-6/{{path}}#{{fragment}}",
 }
 
 intersphinx_mapping = {

diff --git a/docs/source/user_guide/gui.md b/docs/source/user_guide/gui.md
@@ -5,7 +5,8 @@ The `movement` graphical user interface (GUI), powered by our custom plugin for
 [napari](napari:), makes it easy to view and explore `movement`
 motion tracks. Currently, you can use it to
 visualise 2D [movement datasets](target-poses-and-bboxes-dataset)
-as points, tracks, and rectangular bounding boxes (if defined) overlaid on video frames.
+as points, tracks, and rectangular bounding boxes (if defined) overlaid on
+video frames, as well as to define regions of interest (RoIs).
 
 :::{warning}
 The GUI is still in early stages of development but we are working on ironing
@@ -61,7 +62,7 @@ plugin—and click `OK`. You can optionally select to remember this reader
 for all files with the same extension.
 
 
-![napari widget video reader](../_static/napari_plugin_video_reader.png)
+![napari video reader](../_static/napari_video_reader.png)
 
 
 `napari-video` will load the video as an image stack with a slider
@@ -70,7 +71,7 @@ You may also use the left and right arrow keys to navigate
 frame-by-frame.
 
 
-![napari widget video slider](../_static/napari_plugin_video_slider.png)
+![napari video slider](../_static/napari_video_slider.png)
 
 Clicking on the play button will start the video playback at a default
 rate of 10 frames per second. You can adjust the playback speed by right-clicking on the
@@ -199,11 +200,11 @@ For a poses dataset, you will see a view similar to this:
 
 (target-widget-screenshot)=
 
-![napari widget with poses dataset loaded](../_static/napari_plugin_data_tracks.png)
+![napari with poses dataset loaded](../_static/napari_poses_layers.png)
 
 And for a bounding boxes dataset, you will see a view more like the one below:
 
-![napari widget with shapes loaded](../_static/napari_bboxes_layer.png)
+![napari with bboxes dataset loaded](../_static/napari_bboxes_layers.png)
 
 
 Note the additional bounding boxes layer that is loaded for bounding boxes datasets. For both poses and bounding boxes datasets, you can toggle the visibility of any of these layers by clicking on the eye icon.
@@ -230,7 +231,7 @@ and the time in seconds (calculated based on the frame number and
 the `fps` value).
 
 
-![napari points layer tooltip](../_static/napari_points_layer_tooltip.png)
+![napari points tooltip](../_static/napari_points_tooltip.png)
 
 
 
@@ -276,7 +277,7 @@ selected layer shows the trajectories of the keypoints from the current frame un
 end of the video.
 
 
-![napari tracks layer head length](../_static/napari_tracks_layer_head_length.png)
+![napari tracks sliders](../_static/napari_tracks_sliders.png)
 
 
 You can also use the [tracks layer](napari:howtos/layers/tracks.html) controls panel to
@@ -324,3 +325,119 @@ You can find all the [keyboard shortcuts](napari:guides/preferences.html#shortcu
 `napari` window, under `Preferences > Shortcuts`.
 
 :::
+
+## Define regions of interest
+
+The `Define regions of interest` menu allows you to draw shapes on the
+viewer and use them as regions of interest (RoIs) for analysis.
+
+Each shape you draw represents a static region
+that remains fixed across all frames.
+
+:::{admonition} Terminology
+:class: note
+
+**Shape**
+: Any geometric object you draw on the `napari` canvas
+  (e.g. a polygon or a line). Shapes are grouped together in
+  `napari` [shapes layers](napari:howtos/layers/shapes.html).
+
+**Region**
+: A named `napari` shape that `movement` recognises as a
+  region of interest (RoI) for analysis.
+
+**Region layer**
+: A `napari` [shapes layers](napari:howtos/layers/shapes.html) managed
+  by `movement`, whose shapes are treated as **regions**.
+
+:::
+
+
+### Create a region layer
+
+To define a region for your data, start by creating a region layer,
+which will serve as a container. To do this:
+
+1. Ensure a [background layer](target-load-video) is loaded so that you
+   can see where you are drawing.
+2. Expand the `Define regions of interest` menu on the right-hand side
+   of the `napari` window.
+3. Click the `Add new layer` button.
+
+This will create a new region layer in the layer list and select it.
+The layer also appears in the dropdown next to the `Add new layer` button.
+The layer's default name is `regions`, but you can change it by double-clicking
+on it in the layer list (this is the case for any `napari` layer).
+
+![napari new region layer](../_static/napari_new_region_layer.png)
+
+### Draw and edit regions
+
+With the region layer selected, you can use the native `napari` shape tools
+in the layer controls panel to draw shapes on the canvas.
+Convenient keyboard shortcuts are available to select the shape drawing tools,
+for example:
+
+- `R`: rectangle tool
+- `E`: ellipse tool
+- `P`: polygon tool
+- `L`: line tool
+
+Tools are also provided for selecting, moving, transforming,
+and deleting shapes, as well as for editing their vertices.
+You can also copy-paste shapes within a layer.
+See the [napari shapes layer guide](napari:howtos/layers/shapes.html) for
+details on the drawing tools and how to use them.
+
+Each shape you draw is automatically added to the widget's table of regions
+on the right-hand side and auto-assigned a unique name
+(e.g. `region`, `region_1`, `region_2`, etc.).
+
+![napari drawing regions](../_static/napari_drawing_regions.png)
+
+You can interact with the table in the following ways:
+
+- **Select**: clicking a row in the table selects the corresponding shape
+  on the canvas, and vice versa. This makes it easy to identify which
+  shape corresponds to which table entry.
+- **Rename**: double-click the name cell of a region to edit its name.
+  Press `Enter` to confirm the change or `Escape` to cancel.
+- **Delete**: select a shape on the canvas and press `Delete` (or
+  `Backspace`) to remove it. The corresponding row will be removed from
+  the table.
+
+:::{admonition} Changing shape appearance
+:class: tip
+
+You can change the edge colour, face colour, edge width, and opacity of
+shapes by selecting a shape (or multiple shapes)
+and using the `napari` layer controls panel.
+Once a shape's appearance has been adjusted, all subsequent shapes drawn in
+the same layer will inherit those properties by default.
+
+To display region names on the canvas, tick the `display text` checkbox
+in the layer controls panel. The text colour follows the shape's edge
+colour.
+:::
+
+### Save and load regions
+
+Save and load functionality for region layers is coming soon.
+You will be able to save a region layer to a GeoJSON file,
+and load it back later or share it with others. This will also allow you
+to import drawn regions into your Python code using the
+{func}`~movement.roi.load_rois` function.
+
+**Stay tuned!**
+
+### Working with multiple region layers
+
+You can use region layers to group related regions together.
+For example, you might use one layer for "nesting zones" and another for
+"foraging zones".
+
+To add another region layer, click the `Add new layer` button again.
+You can switch between region layers using the layers dropdown, or by
+selecting the layer directly in the `napari` layer list—both are kept in sync.
+The regions table updates to show only the shapes
+belonging to the selected layer.
diff --git a/movement/napari/layer_styles.py b/movement/napari/layer_styles.py
@@ -4,6 +4,8 @@
 
 import numpy as np
 import pandas as pd
+from napari.layers import Shapes
+from napari.utils.color import ColorValue
 from napari.utils.colormaps import ensure_colormap
 
 DEFAULT_COLORMAP = "turbo"
@@ -123,7 +125,7 @@ def set_color_by(self, property: str, cmap: str | None = None) -> None:
 
 @dataclass
 class BoxesStyle(LayerStyle):
-    """Style properties for a napari Shapes layer."""
+    """Style properties for a napari Shapes layer containing bounding boxes."""
 
     edge_width: int = 3
     opacity: float = 1.0
@@ -190,6 +192,70 @@ def set_text_by(self, property: str) -> None:
         self.text["string"] = property
 
 
+@dataclass
+class RegionsStyle(LayerStyle):
+    """Style properties for a napari Shapes layer containing regions.
+
+    The same ``color`` is applied to faces, edges, and text.
+    The face color alpha is hardcoded to 0.25, while edges and text are
+    fully opaque. Overall layer opacity is set to 1.0.
+    """
+
+    name: str = "Regions"
+    color: str | tuple = "red"
+    edge_width: float = 5.0
+    opacity: float = 1.0
+    text: dict = field(
+        default_factory=lambda: {
+            "visible": False,
+            "anchor": "center",
+        }
+    )
+
+    @property
+    def face_color(self) -> ColorValue:
+        """Return the face color with transparency applied."""
+        color = ColorValue(self.color)
+        color[-1] = 0.25  # this is hardcoded for now
+        return color
+
+    @property
+    def edge_and_text_color(self) -> ColorValue:
+        """Return the opaque color for edges and text."""
+        color = ColorValue(self.color)
+        color[-1] = 1.0
+        return color
+
+    def set_style_for_new_shapes(self, layer: Shapes) -> None:
+        """Set the style that napari will apply to newly drawn shapes.
+
+        napari uses current_* properties to style shapes as they are drawn.
+        """
+        layer.current_face_color = self.face_color
+        layer.current_edge_color = self.edge_and_text_color
+        layer.current_edge_width = self.edge_width
+
+    def set_color_all_shapes(self, layer: Shapes) -> None:
+        """Set colors on all existing shapes in a napari Shapes layer."""
+        # Configure text appearance
+        text_dict = layer.text.dict()
+        text_dict.update(self.text)
+        layer.text = text_dict
+        layer.text.color = self.edge_and_text_color
+
+        # Set layer opacity and per-shape face/edge colors
+        layer.opacity = self.opacity
+        n_shapes = len(layer.data)
+        if n_shapes > 0:
+            layer.face_color = [self.face_color] * n_shapes
+            layer.edge_color = [self.edge_and_text_color] * n_shapes
+            layer.edge_width = [self.edge_width] * n_shapes
+            layer.text.string = "{name}"
+            layer.text.refresh(layer.features)
+
+        self.set_style_for_new_shapes(layer)
+
+
 def _sample_colormap(n: int, cmap_name: str) -> list[tuple]:
     """Sample n equally-spaced colors from a napari colormap.
 

diff --git a/movement/napari/loader_widgets.py b/movement/napari/loader_widgets.py
@@ -396,12 +396,19 @@ def _update_frame_slider_range(self):
         with all NaN values, the frame slider range will not reflect
         the full range of frames.
         """
+
+        def _layer_has_data(layer):
+            if isinstance(layer, Shapes):
+                return len(layer.data) > 0
+            return layer.data.shape[0] > 0
+
         # Only update the frame slider range if there are layers
-        # that are Points, Tracks, Image or Shapes
+        # that are Points, Tracks, Image or Shapes with data
         list_layers = [
             ly
             for ly in self.viewer.layers
             if isinstance(ly, Points | Tracks | Image | Shapes)
+            and _layer_has_data(ly)
         ]
         if len(list_layers) > 0:
             # Get the maximum frame index from all candidate layers