Feature: Usability improvements in regarding cell masks

[yulewu]

Currently, the mask painter only supports either outline or filled display modes for each class. However, it would be beneficial to have the option to display borders on top of filled masks. This would allow users to better distinguish adjacent cells of the same class and improve overall visibility.

Also, the filled masks' opacity is currently fixed and not rendered at 100%. Allowing users to adjust the opacity of filled masks would provide greater flexibility in visualizing the underlying image data while still benefiting from the color-coding of the masks.

Sometimes it even better for the filled masks to be fully opaque, when the user is only interested in the spatial distribution of a particular class and not the image data. In this case, the option to set filled masks to 100% opacity would be particularly useful.

As well, it would be great to set opacity to 0% (fully transparent) for some classes, effectively rendering them as outlines only. This would allow users to have a clear view of the image data while still being able to identify the boundaries of cells in that class.

Involved plugins

• Mask Painter: this is where the UI controls for outline/fill and opacity would be implemented, as well as the logic to apply these settings to the cell masks.
• Cell Gallery: the gallery should reflect the same outline/fill and opacity settings as the main viewer to maintain consistency in how classes are represented across the UI.
• Batch Export: when exporting images with masks, the export pipeline should also respect the outline/fill and opacity settings to ensure that exported images match what users see in the viewer.
• ROI manager: if ROIs are colored based on cell classes, the ROI manager should also apply the same outline/fill and opacity settings to maintain visual consistency.

UI suggestions

• Add a toggle for "Show borders on filled masks" in the Mask Painter UI. When enabled, this would render a thin border around filled masks, using the current color for the masks.
• Add a field for "Filled mask opacity" in the Mask Painter UI per class, allowing users to set the opacity level for filled masks. When set to 0%, filled masks would become fully transparent, effectively rendering them as outlines only. When set to 100%, filled masks would be fully opaque.
• Add a global opacity field in the Mask Painter UI that allows users to adjust the opacity of all filled masks with the global value simultaneously, while still respecting individual class settings. This would provide an easy way to quickly adjust visibility without having to change each class individually.

[yulewu]

Update Summary: Mask Painter opacity and fill borders (commit d8fa15f)

Implemented issue #91 so mask painter fill opacity and border behavior are available in the live viewer and preserved across snapshot-based consumers.

---

Actions Taken

• Added per-class and global fill opacity controls:
  mask_class_list_widget.py and mask_painter.py now track per-class opacity, a global linked-opacity control, and a show_fill_borders toggle.
• Updated live render paths:
  mask_color_overlay.py and main_viewer.py now render painter-controlled fill opacity and optional borders consistently in single-FOV and map-mode overlays.
• Added painter snapshot capture/replay:
  rendering/engine.py now includes MaskPainterSnapshot, and main_viewer.py can resolve and replay painter snapshots for other consumers.
• Propagated painter state to downstream consumers:
  export_fovs.py, roi_manager.py, roi_manager_plugin.py, and cell_gallery.py now preserve or replay painter fill/opacity/border settings instead of forcing outline-only behavior.
• Added regression coverage:
  Added focused tests for overlay fill opacity, painter snapshot capture/restore, export snapshot preservation, ROI payload persistence, and cell gallery fill-plus-border rendering.

---

Files Changed

• ueler/rendering/engine.py — added MaskPainterSnapshot and extended OverlaySnapshot
• ueler/rendering/__init__.py — re-exported painter snapshot types
• ueler/viewer/rendering.py — re-exported painter snapshot types
• ueler/viewer/plugin/mask_class_list_widget.py — added per-class opacity UI state
• ueler/viewer/plugin/mask_painter.py — added opacity controls, snapshot capture/restore, and linked global opacity logic
• ueler/viewer/mask_color_overlay.py — added per-cell opacity and optional borders-on-fill rendering
• ueler/viewer/main_viewer.py — added painter snapshot capture, resolution, and replay helpers
• ueler/viewer/plugin/export_fovs.py — preserved painter snapshots in export capture and replayed them after rendering
• ueler/viewer/roi_manager.py — added mask_painter_state ROI persistence column
• ueler/viewer/plugin/roi_manager_plugin.py — stored and restored ROI painter snapshots and replayed them for thumbnails
• ueler/viewer/plugin/cell_gallery.py — used captured painter state for painted fill/opacity/border rendering
• tests/test_mask_color_overlay.py — added fill-opacity and fill-border overlay regressions
• tests/test_mask_painter_mode_visibility.py — added opacity-linking and painter snapshot regressions
• tests/test_export_fovs_batch.py — added export painter snapshot preservation regression
• tests/test_roi_manager_tags.py — added ROI painter payload regression
• tests/test_cell_gallery.py — added painted gallery snapshot fill/border regression

---

Tests

python -m unittest tests.test_mask_painter_mode_visibility tests.test_mask_color_overlay tests.test_cell_gallery tests.test_roi_manager_tags
python -m unittest tests.test_export_fovs_batch.ExportFOVsBatchTests.test_batch_export_snapshot_preserves_mask_painter_outline_thickness

• ✅ All tests passed

[yulewu]

Two issues to address

1. Opacity changes are not reflected in the ROI thumbnails:
   When a view is captured as a ROI, the current mask painter state (including fill opacity and border settings) should be captured and applied to the ROI thumbnail rendering. This ensures that the thumbnails accurately represent the current visualization settings of the viewer. Also, when center on a ROI, the main viewer should apply the captured painter state to the main overlay so that the user sees a consistent representation between the thumbnail and the main view.
2. Outline color should match the mask color:
   When "Show borders on filled masks" is enabled, the border color should match the specified mask color for the mask type (the UI in the left panel), not necessarily the fill color. This ensures that the borders are visually consistent with the mask color, improving the overall clarity and aesthetics of the visualization. The border should also update dynamically if the user changes the mask color or toggles the border option, maintaining a cohesive look. However, using same color for both fill and border can be offered as an option.

[yulewu]

Update Summary: Mask Painter ROI replay and border-color follow-up (commit f46a10b)

Implemented the reply-to-#91 follow-up so map-mode ROI thumbnails/exports replay the saved painter snapshot and filled-mask borders can use either the mask-type color or the fill color.

---

Actions Taken

• Added a distinct filled-border color path:
  mask_color_overlay.py now accepts border_color_map, and the live viewer, gallery, and snapshot replay paths can render fill and border colors independently.
• Extended painter snapshots for border-color replay:
  rendering/engine.py and mask_painter.py now store border_color_mode plus the resolved mask-type color, and the painter UI exposes a new border-color mode dropdown.
• Fixed map-mode ROI replay:
  main_viewer.py now provides a stitched-map snapshot replay helper, and roi_manager_plugin.py plus export_fovs.py reuse it so map-mode ROI thumbnails and map ROI export match the saved painter state.
• Updated downstream consumers and regressions:
  cell_gallery.py now uses the richer painter replay tuple, and focused tests were added for border-color replay, map-mode ROI thumbnail replay, and map ROI export replay.

---

Files Changed

• ueler/rendering/engine.py — extended MaskPainterSnapshot with border-color replay state
• ueler/viewer/plugin/mask_painter.py — added border-color mode UI/state and stored resolved mask-type colors in snapshots
• ueler/viewer/mask_color_overlay.py — added border_color_map support for filled-mask borders
• ueler/viewer/main_viewer.py — forwarded border-color maps through live rendering and added stitched-map snapshot replay
• ueler/viewer/plugin/roi_manager_plugin.py — replayed painter snapshots for map-mode ROI thumbnails and restored new snapshot fields
• ueler/viewer/plugin/export_fovs.py — replayed painter snapshots for map ROI export
• ueler/viewer/plugin/cell_gallery.py — used distinct border colors during gallery replay
• tests/test_mask_color_overlay.py — added distinct-border-color regression
• tests/test_mask_painter_mode_visibility.py — added border-color snapshot/render-path regressions
• tests/test_roi_manager_tags.py — added map-mode ROI thumbnail replay regression
• tests/test_cell_gallery.py — updated gallery replay assertions for distinct border colors
• tests/test_export_fovs_batch.py — added map ROI export replay assertion

---

Tests

python -m unittest tests.test_mask_color_overlay tests.test_mask_painter_mode_visibility tests.test_roi_manager_tags tests.test_cell_gallery
python -m unittest tests.test_export_fovs_batch.BatchExportMapROIItemsTests.test_export_map_roi_worker_calls_render_map_region_direct tests.test_export_fovs_batch.BatchExportMapROIItemsTests.test_export_map_roi_worker_applies_map_bounds_offset tests.test_export_fovs_batch.BatchExportMapROIItemsTests.test_export_map_roi_worker_raises_on_empty_roi

• ✅ All tests passed

[yulewu]

Update Summary: Mask Painter NumPy-backed current-FOV recolor fix (commit 2d8f062)

Implemented reply 2 to issue #91 by fixing the immediate current-FOV recolor path to accept either NumPy-backed or lazy label-mask data.

---

Actions Taken

• Fixed the owning image-display path:
  image_display.py now materializes array-like inputs inside set_mask_colors_current_fov() before np.where(...) and after generate_edges(...), so the code no longer calls .compute() on a NumPy array.
• Kept the caller unchanged:
  MaskPainterDisplay.apply_colors_to_masks() still uses the same immediate current-FOV highlight helper; the array-type handling now lives where the mask and edge data are actually consumed.
• Added a focused regression:
  tests/test_image_display_tooltip.py now covers the NumPy-backed mask path that previously raised AttributeError.

---

Files Changed

• ueler/viewer/image_display.py — materialized eager/lazy arrays in set_mask_colors_current_fov() before contour generation and indexing
• tests/test_image_display_tooltip.py — added NumPy-backed current-FOV recolor regression and completed the lightweight image_utils stub used in the same unittest process

---

Tests

python -m unittest tests.test_image_display_tooltip tests.test_mask_painter_mode_visibility

• ✅ All tests passed

[yulewu]

Mask Painter border overlay made fill color values "dimmer"

When the "Show borders on filled masks" option is enabled in the Mask Painter, the borders are rendered on top of the filled masks. However, this somehow changed the filled color values and make them dimmer than intended, causing them less vibrant and harder to distinguish. The idea is that the borders end their expaned pixels should just overwrite the filled mask pixels without altering the underlying fill color values.

[yulewu]

Update Summary: Mask Painter filled-border dimming fix (commit 43dc503)

Fixed the filled-border rendering regression so enabling Show borders on filled masks no longer alters neighboring fill colors or makes adjacent filled cells look dimmer.

---

Actions Taken

• Separated fill and border compositing in the shared helper:
  mask_color_overlay.py now blends fills first and paints borders afterward instead of interleaving both operations cell-by-cell.
• Clipped thickened filled borders to the owning cell:
  Thickened borders for filled-mask rendering are now intersected with the cell's own mask before painting, so the expanded border ring no longer spills into adjacent cells.
• Added a focused regression:
  tests/test_mask_color_overlay.py now includes an adjacent-cell regression proving a thickened filled border cannot re-blend or overwrite a neighboring cell's interior fill value.

---

Files Changed

• ueler/viewer/mask_color_overlay.py — switched filled-mask rendering to fill-first/border-second and clipped thickened filled borders to the owning mask
• tests/test_mask_color_overlay.py — added adjacent-cell filled-border dimming regression

---

Tests

python -m unittest tests.test_mask_color_overlay
python -m unittest tests.test_mask_painter_mode_visibility

• ✅ All tests passed

[yulewu]

Request a mask-only mode

In addition to the current outline and filled display modes, it would be beneficial to have a mask-only mode where the masks are displayed without any underlying image data. This mode would allow users to focus solely on the spatial distribution and relationships of the cells without the distraction of the image background. To improve the efficiency of this mode, we can add a "no image" option to the display settings, and literally not render the image layer when this option is selected. This would reduce the computational load and potentially improve performance when users are only interested in analyzing the masks themselves. The reason to call it "no image" instead of "mask-only" is that this is controlling the rendering of the image layer, not the mask layer, so "no image" is more accurate and less likely to cause confusion about what is being toggled. Therefore, this should be added to the left panel, perhaps as a checkbox labeled "No image (masks only)", above channel settings. It should be grayed out when no masks are present, and when enabled, the image layer should be hidden while still rendering the masks with their assigned colors and opacities.

[yulewu]

Update Summary: No image (masks only) mode (commit f9c9996)

Implemented the requested No image (masks only) mode so the viewer can skip image-layer rendering while keeping masks and annotations visible on a black background, with the same behavior propagated to export, ROI thumbnails, and the cell gallery.

---

Actions Taken

• Viewer control and state wiring:
  Added a left-panel No image (masks only) checkbox in ui_components.py, disabled it when masks are unavailable, and wired main_viewer.py to redraw immediately when the state changes.
• Shared render-flag support:
  Extended render_fov_to_array, render_crop_to_array, and render_roi_to_array in rendering/engine.py with skip_image_layer, allowing black-base overlay rendering even when no channels are selected.
• Map-mode parity:
  Added the no-image state to _map_state_signature(...) and cleared stitched-map tile cache on toggle so map-mode tiles do not stay image-backed after switching modes.
• Downstream propagation:
  Carried the state through OverlaySnapshot, then forwarded it in export_fovs.py, roi_manager_plugin.py, and cell_gallery.py so export, ROI thumbnails, and gallery tiles honor the same no-image mode.
• Plugin refresh hooks:
  Added a plugin lifecycle hook for the display-mode toggle and used it to refresh ROI thumbnails and the cell gallery when the mode changes.

---

Files Changed

• ueler/rendering/engine.py — added skip_image_layer support and overlay-only black-base rendering
• ueler/viewer/main_viewer.py — added viewer state/callback, map signature update, live-render forwarding, and snapshot capture support
• ueler/viewer/ui_components.py — added the No image (masks only) checkbox to the left panel
• ueler/viewer/plugin/plugin_base.py — added on_no_image_toggle() lifecycle hook
• ueler/viewer/plugin/export_fovs.py — forwarded the no-image snapshot flag through full-FOV, crop, ROI, and map ROI exports
• ueler/viewer/plugin/roi_manager_plugin.py — carried the no-image state into ROI thumbnail snapshots and refresh behavior
• ueler/viewer/plugin/cell_gallery.py — forwarded the no-image snapshot flag into gallery crop rendering and refreshed on toggle
• tests/test_rendering.py — added shared render-engine regressions for black-base overlay rendering
• tests/test_mask_painter_mode_visibility.py — added viewer forwarding and map-signature regressions
• tests/test_export_fovs_batch.py — added export snapshot/forwarding regressions
• tests/test_cell_gallery.py — added gallery forwarding regression
• tests/test_roi_manager_tags.py — added ROI snapshot propagation regression

---

Tests

python -m unittest tests.test_rendering.RenderingHelpersTests.test_render_fov_to_array_skips_image_layer_but_preserves_masks tests.test_rendering.RenderingHelpersTests.test_render_fov_to_array_without_channels_can_render_overlays tests.test_mask_painter_mode_visibility.TestMaskPainterRenderPath tests.test_export_fovs_batch.ExportFOVsBatchTests.test_capture_overlay_snapshot_and_rebuild tests.test_export_fovs_batch.BatchExportMapROIItemsTests.test_export_map_roi_worker_calls_render_map_region_direct tests.test_export_fovs_batch.BatchExportMapROIItemsTests.test_render_map_region_direct_uses_render_fov_to_array_per_tile tests.test_export_fovs_batch.BatchExportMapROIItemsTests.test_export_map_roi_worker_applies_map_bounds_offset tests.test_cell_gallery.TestCellGalleryColors.test_gallery_forwards_skip_image_layer_from_snapshot tests.test_roi_manager_tags.ROIManagerMapModeTests.test_build_overlay_snapshot_carries_no_image_mode

• ✅ All focused tests passed
• ℹ️ python -m unittest tests.test_mask_painter_mode_visibility tests.test_export_fovs_batch tests.test_cell_gallery tests.test_roi_manager_tags still reports the pre-existing unrelated failure in tests.test_export_fovs_batch.ExportFOVsBatchTests.test_export_fovs_batch_writes_file

[yulewu]

Bugs in the Mask Painter Plugin

1. Global opacity is not linked to class settings
   When adjusting the global fill opacity in the Mask Painter, it does not affect individual classes that are set to use the global opacity value. Since using the same value as the global opacity implies that a class inherits it, changing the global opacity should trigger an update for all classes configured this way.

2. Request: global fill toggle
   In addition to the global fill opacity control, it would be helpful to have a global fill toggle that enables or disables filling for all inactive classes at once. This would let users quickly switch between outline-only and filled modes without adjusting each class individually. The toggle should be placed near the global fill opacity control for easy access.

3. Behavior of the Only Specified toggle
   When the Only Specified toggle is enabled, classes with user-defined colors should be sorted to the top of the class list. This makes it easier for users to find and focus on their customized classes while still having access to default-colored classes further down the list.

4. All settings should be saved in the color set
   When saving a color set in the Mask Painter, all current settings — including fill/outline mode, opacity levels, and border visibility — should be captured in the saved palette. This ensures that loading a color set restores the exact visual configuration from when it was saved, with no need to manually reapply any settings. To accommodate older palettes that lack these fields, any missing settings should fall back to their global defaults on load, and the save function should be updated to include all settings going forward.