Rename monochromatic color mode and add descriptions (#2894)

* show description in UI for color_mode
* deprecated API support for "Monochromatic"
* update tests/docs/comments

CHANGES.rst

@@ -11,6 +11,9 @@ New Features
 
 - New "About" plugin to show Jdaviz version info. [#2886]
 
+- Descriptions are shown in the color mode dropdown for image layers to help describe the use-cases
+  for ``Colormap`` vs ``Color``. [#2894]
+
 Cubeviz
 ^^^^^^^
 
@@ -37,6 +40,10 @@ Specviz2d
 API Changes
 -----------
 
+- The ``Monochromatic`` option for ``color_mode`` in plot options is now renamed to ``Color``.
+  ``Monochromatic`` will continue to work with a deprecation warning, but may be removed in a
+  future release. [#2894]
+
 Cubeviz
 ^^^^^^^
 

docs/imviz/displayimages.rst

@@ -288,10 +288,10 @@ Color mode
 ----------
 
 This option allows you to choose whether to use a colormap or or a single color to visualize the image.
-The colormap can be selected from a dropdown within the Layer tab. In monochromatic mode, the color
+The colormap can be selected from a dropdown within the Layer tab. In "Color" mode, the color
 can be chosen from a color picker under "Image Color" within the Layer tab.
 
-In monochromatic mode, the option "Assign RGB presets" appears. This will automatically
+In "Color" mode, the option "Assign RGB presets" appears. This will automatically
 assign colors spanning from blue to red to the available layers and will adjust opacity and
 stretch to produce a composite color image (also known as RGB image). You will then
 be able to fine tune all options within each Layer tab.

jdaviz/configs/default/plugins/plot_options/plot_options.py

@@ -187,7 +187,7 @@ class PlotOptions(PluginTemplateMixin):
     * ``image_color_mode`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
       not exposed for Specviz
     * ``image_color`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
-      not exposed for Specviz.  This only applies when ``image_color_mode`` is "Monochromatic".
+      not exposed for Specviz.  This only applies when ``image_color_mode`` is "Color".
     * ``image_colormap`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
       not exposed for Specviz. This only applies when ``image_color_mode`` is "Colormap".
     * ``image_opacity`` (:class:`~jdaviz.core.template_mixin.PlotOptionsSyncState`):
@@ -769,12 +769,12 @@ def vue_set_value(self, data):
     def apply_RGB_presets(self):
         """
         Applies preset colors, opacities, and stretch settings to all visible layers
-        (in all viewers) when in Monochromatic mode.
+        (in all viewers) when in Color (Monochromatic) mode.
         """
 
         if (self.image_color_mode_value != "One color per layer" or
                 self.image_color_mode_sync['mixed']):
-            raise ValueError("RGB presets can only be applied if color mode is Monochromatic.")
+            raise ValueError("RGB presets can only be applied if color mode is Color.")
         # Preselected colors we want to use for 5 or less layers
         preset_colors = [self.swatches_palette[4][1],
                          "#0000FF",
@@ -1088,7 +1088,7 @@ def _update_stretch_curve(self, msg=None):
             # Compute colormapped image
             plane = layer_cmap(data)
 
-        else:  # Monochromatic
+        else:  # Color (Monochromatic)
             # Get color
             color = COLOR_CONVERTER.to_rgba_array(self.image_color_value)[0]
             plane = data[:, np.newaxis] * color

jdaviz/configs/default/plugins/plot_options/plot_options.vue

@@ -138,10 +138,26 @@
           :items="image_color_mode_sync.choices"
           v-model="image_color_mode_value"
           label="Color Mode"
-          hint="Whether each layer gets a single color or colormap"
-          persistent-hint
-          dense
-        ></v-select>
+          hint="Whether each layer gets a single color or colormap."
+          persistent-hint 
+          dense 
+        >
+          <template v-slot:selection="{ item }">
+            <span>
+              {{ item.text }}
+            </span>
+          </template>
+          <template v-slot:item="{ item }">
+            <span>
+              <b>
+                {{ item.text }}
+              </b>
+              <span v-if="item.description" style="opacity: 0.85; font-size: 10pt">
+                | {{ item.description }}
+              </span>
+            </span>
+          </template>
+        </v-select>
       </glue-state-sync-wrapper>
     </div>
 

jdaviz/configs/default/plugins/plot_options/tests/test_plot_options.py

@@ -267,7 +267,7 @@ def test_apply_presets(imviz_helper):
     for i in range(4):
         imviz_helper.load_data(arr, data_label=f"array_{i}")
 
-    po.image_color_mode = "Monochromatic"
+    po.image_color_mode = "Color"
     po.apply_RGB_presets()
 
     for i in range(4):

jdaviz/core/template_mixin.py

@@ -6,6 +6,7 @@
 import bqplot
 from contextlib import contextmanager
 import numpy as np
+import logging
 import os
 import threading
 import time
@@ -4152,8 +4153,12 @@ def _get_glue_choices(self, state):
             helper = getattr(state, f'{glue_name}_helper')
             return [{'text': str(choice), 'value': str(choice)} for choice in helper.choices]
         if glue_name == 'color_mode':
-            return [{'text': 'Colormap', 'value': 'Colormaps'},
-                    {'text': 'Monochromatic', 'value': 'One color per layer'}]
+            return [{'text': 'Colormap',
+                     'value': 'Colormaps',
+                     'description': 'Select a colormap per-layer. Only top-layer will be visible without adjusting opacity.'},  # noqa
+                    {'text': 'Color',
+                     'value': 'One color per layer',
+                     'description': 'Select a color per-layer. Layers will be composited.'}]
 
         values, labels = _get_glue_choices(state, glue_name)
         return [{'text': l, 'value': v} for v, l in zip(values, labels)]
@@ -4271,6 +4276,11 @@ def _on_value_changed(self, msg):
         if self._spinner is not None:
             setattr(self.plugin, self._spinner, True)
 
+        if self._glue_name == 'color_mode' and msg['new'] == 'Monochromatic':
+            logging.warning("DeprecationWarning: 'Monochromatic' renamed to 'Color'")
+            self.value = 'One color per layer'
+            return
+
         self._processing_change_to_glue = True
         for glue_state in self.linked_states:
             glue_name = self.glue_name(glue_state)

notebooks/concepts/cubeviz_ndarray_gif.ipynb

@@ -270,7 +270,7 @@
    "outputs": [],
    "source": [
     "plot_plg.viewer = \"flux-viewer\"\n",
-    "plot_plg.image_color_mode = \"Monochromatic\"\n",
+    "plot_plg.image_color_mode = \"Color\"\n",
     "plot_plg.image_color = \"Red\""
    ]
   },
@@ -284,7 +284,7 @@
    "outputs": [],
    "source": [
     "plot_plg.viewer = \"uncert-viewer\"\n",
-    "plot_plg.image_color_mode = \"Monochromatic\"\n",
+    "plot_plg.image_color_mode = \"Color\"\n",
     "plot_plg.image_color = \"Blue\""
    ]
   },

notebooks/concepts/imviz_colorbar_mpl.ipynb

@@ -134,8 +134,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# Monochromatic\n",
-    "#plg.image_color_mode = \"Monochromatic\"\n",
+    "# Color (Monochromatic / RGB)\n",
+    "#plg.image_color_mode = \"Color\"\n",
     "#plg.image_color = \"red\""
    ]
   },

notebooks/concepts/imviz_dithered_gwcs.ipynb

@@ -113,7 +113,7 @@
    "outputs": [],
    "source": [
     "# Set color mode to easily distinguish between them\n",
-    "imviz.plugins['Plot Options'].image_color_mode = 'Monochromatic'"
+    "imviz.plugins['Plot Options'].image_color_mode = 'Color'"
    ]
   },
   {