Merge pull request #14 from Kitware/feature/nan-color-dropdown

feat: add NaN color dropdown to toolbar

Author: patrickoleary

README.md

@@ -113,9 +113,10 @@ The control panel has three sections, top to bottom:
 
 The toolbar has three areas, left to right:
 
-- **Icon buttons** — Seven buttons separated into three groups by vertical
+- **Icon buttons** — Eight buttons separated into three groups by vertical
   dividers. Active toggles show a primary-colored square outline; the icon
-  itself stays black. Details on each button below.
+  itself stays black. The NaN color button opens a dropdown instead of
+  toggling. Details on each button below.
 
 - **Search / preset name** — Shows the name of the currently active preset.
   Click into it to type and filter the preset list by name. Use the clear
@@ -135,9 +136,10 @@ The toolbar has three areas, left to right:
 | 3 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/palette.svg" width="24"> | — | Category | Opens a dropdown to select one preset category (Sequential, Multi-Sequential, Diverging, Cyclic). Default is Sequential. Disabled in Δ mode. |
 | 4 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/blinds.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/blinds.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Colorblind Safe | Limits the *Preset list* to colorblind-safe presets within the active category. |
 | 5 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/invert-colors.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/invert-colors.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Invert | Reverses the colormap direction (shown in the *Colorbar* and *Preset list*). |
+| 6 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/crosshairs-question.svg" width="24"> | — | NaN Color | Opens a dropdown to select the color used for NaN/missing data. Default is transparent. Shows a color swatch and situation label for each option. |
 | | | | | |
-| 6 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/gradient-horizontal.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/gradient-horizontal.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Discrete | Switches between continuous gradient and discrete color banding. Exposes band count in *Settings panel*. |
-| 7 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/pencil.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/pencil.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Custom Range | Toggles between data-driven range and manual Min/Max inputs. Disabled in Δ mode. Cannot be active at the same time as Δ Difference. |
+| 7 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/gradient-horizontal.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/gradient-horizontal.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Discrete | Switches between continuous gradient and discrete color banding. Exposes band count in *Settings panel*. |
+| 8 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/pencil.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/pencil.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Custom Range | Toggles between data-driven range and manual Min/Max inputs. Disabled in Δ mode. Cannot be active at the same time as Δ Difference. |
 
 Empty rows in the table indicate the vertical separator dividers between
 button groups.
@@ -150,6 +152,23 @@ button groups.
 - **Category dropdown** is disabled when Δ Difference is on (presets forced
   to Diverging). When Δ is turned off, category resets to Sequential.
 
+#### NaN Color Dropdown
+
+The NaN Color button (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/crosshairs-question.svg" width="16">)
+opens a scrollable dropdown with 19 preset options. Each row shows a color
+swatch circle and a situation label. Options are grouped:
+
+| Group | Options |
+|-------|---------|
+| **Default** | transparent, general |
+| **Colormap types** | sequential maps, diverging maps, categorical maps, grayscale maps, bright maps, dark maps, hot maps, terrain final |
+| **Data quality** | error, warning, suspect data, masked data, debugging |
+| **Background/context** | light background, dark background, publication light, publication dark |
+
+The default is **transparent** (`rgba(0,0,0,0)`), meaning NaN cells are
+invisible. The selected color is applied via `vtkColorTransferFunction.SetNanColorRGBA()`
+on both the main CTF and any render CTF (e.g. symlog).
+
 #### Scale Modes
 
 <table>
@@ -213,6 +232,7 @@ from trame.widgets.colormaps import HorizontalScalarBar, VerticalScalarBar, Colo
 | `VerticalScalarBar` | `trame_colormaps.widgets` | Vertical colorbar widget with built-in control panel |
 | `ColorMapEditor` | `trame_colormaps.widgets` | Preset picker / control panel popup (used internally by scalar bars) |
 | `buttons` | `trame_colormaps.widgets` | Returns button config dicts for the control panel toolbar |
+| `NAN_COLOR_OPTIONS` | `trame_colormaps.widgets` | List of 19 NaN color presets with RGBA values and situation labels |
 
 ## Preset Data Sources
 
@@ -501,6 +521,7 @@ subclass. Fields fall into three groups:
 | `color_value_min` | `str` | `"0"` | Manual range min (string for text field) |
 | `color_value_max` | `str` | `"1"` | Manual range max (string for text field) |
 | `override_range` | `bool` | `False` | Use manual range instead of data range |
+| `nan_color` | `list[float]` | `[0,0,0,0]` | RGBA color for NaN/missing values (transparent by default) |
 | **Derived (computed internally, read by UI)** ||||
 | `color_range` | `tuple[float, float]` | `(0, 1)` | Active min/max color range |
 | `color_value_min_valid` | `bool` | `True` | Whether `color_value_min` parses as a valid float |
@@ -516,6 +537,7 @@ subclass. Fields fall into three groups:
 | `menu` | `bool` | `False` | Whether the control panel popup is open |
 | `search` | `str \| None` | `None` | Preset search filter text |
 | `orientation` | `str` | `"horizontal"` | Colorbar orientation |
+| `show_nan_menu` | `bool` | `False` | Whether the NaN color dropdown is open |
 | `mapper_change` | `int` | `0` | Server-only counter incremented on each mapper update |
 
 ### ColormapConfig Methods

src/trame_colormaps/dataclasses.py

@@ -131,17 +131,22 @@ class ColormapConfig(StateDataModel):
     luts_normal: list = Sync(list, list)
     luts_inverted: list = Sync(list, list)
 
+    # --- NaN color ---
+    nan_color: list[float] = Sync(list, [0.0, 0.0, 0.0, 0.0])
+
     # --- UI widget state (control panel popup) ---
     menu: bool = Sync(bool, False)
     search: str | None = Sync(str)
     orientation: str = Sync(str, "horizontal")
     mapper_change: int = ServerOnly(int, 0)
     show_categories: bool = Sync(bool, False)
     selected_categories: str = Sync(str, "sequential")
+    show_nan_menu: bool = Sync(bool, False)
 
     def __init__(self, *args, mapper=None, data_array_fn=None, **kwargs):
         # Create and own the CTF
         self._ctf = vtkColorTransferFunction()
+        self._ctf.SetNanColorRGBA(0.0, 0.0, 0.0, 0.0)
         self._mapper = mapper
         self._get_data_array = data_array_fn
 
@@ -788,5 +793,22 @@ def update_color_preset(
             self._mapper.SetLookupTable(self._ctf)
 
         self._mapper.SetScalarRange(self.color_range)
+        self._apply_nan_color()
+
+        self.mapper_change += 1
 
+    @watch("nan_color", eager=True)
+    def _on_nan_color_change(self, nan_color):
+        """Apply NaN color to the active CTF(s) whenever it changes."""
+        self._apply_nan_color()
         self.mapper_change += 1
+
+    def _apply_nan_color(self):
+        """Set NaN color (RGBA) on all active CTFs."""
+        c = self.nan_color
+        if not c or len(c) < 4:
+            c = [0.0, 0.0, 0.0, 0.0]
+        r, g, b, a = float(c[0]), float(c[1]), float(c[2]), float(c[3])
+        self._ctf.SetNanColorRGBA(r, g, b, a)
+        if hasattr(self, "_symlog_ctf") and self._symlog_ctf:
+            self._symlog_ctf.SetNanColorRGBA(r, g, b, a)

src/trame_colormaps/widgets.py

@@ -10,6 +10,32 @@
     "VerticalScalarBar",
 ]
 
+NAN_COLOR_OPTIONS = [
+    # Default
+    {"color": [0.0, 0.0, 0.0, 0.0], "situation_preset_type": "transparent"},
+    {"color": [0.75, 0.75, 0.75, 1.0], "situation_preset_type": "general"},
+    # Colormap types
+    {"color": [0.85, 0.85, 0.85, 1.0], "situation_preset_type": "sequential maps"},
+    {"color": [0.60, 0.60, 0.60, 1.0], "situation_preset_type": "diverging maps"},
+    {"color": [0.80, 0.80, 0.80, 1.0], "situation_preset_type": "categorical maps"},
+    {"color": [0.22, 0.49, 0.72, 1.0], "situation_preset_type": "grayscale maps"},
+    {"color": [0.0, 0.0, 0.0, 1.0], "situation_preset_type": "bright maps"},
+    {"color": [1.0, 1.0, 1.0, 1.0], "situation_preset_type": "dark maps"},
+    {"color": [0.0, 1.0, 1.0, 1.0], "situation_preset_type": "hot maps"},
+    {"color": [0.74, 0.74, 0.74, 1.0], "situation_preset_type": "terrain final"},
+    # Data quality
+    {"color": [0.89, 0.10, 0.11, 1.0], "situation_preset_type": "error"},
+    {"color": [1.0, 1.0, 0.20, 1.0], "situation_preset_type": "warning"},
+    {"color": [1.0, 0.50, 0.0, 1.0], "situation_preset_type": "suspect data"},
+    {"color": [0.30, 0.69, 0.29, 1.0], "situation_preset_type": "masked data"},
+    {"color": [1.0, 0.0, 1.0, 1.0], "situation_preset_type": "debugging"},
+    # Background/context
+    {"color": [0.55, 0.55, 0.55, 1.0], "situation_preset_type": "light background"},
+    {"color": [0.33, 0.33, 0.33, 1.0], "situation_preset_type": "dark background"},
+    {"color": [0.94, 0.94, 0.94, 1.0], "situation_preset_type": "publication light"},
+    {"color": [0.15, 0.15, 0.15, 1.0], "situation_preset_type": "publication dark"},
+]
+
 
 def buttons(name):
     return [
@@ -80,6 +106,12 @@ def buttons(name):
             "tip": (f"'Toggle to ' + ({name}.invert ? 'Normal Preset' : 'Invert Preset')"),
             "active": f"{name}.invert",
         },
+        {
+            "icon": "mdi-crosshairs-question",
+            "tip": "'NaN Color'",
+            "active": "false",
+            "nan_menu": True,
+        },
         {"separator": True},
         {
             "icon": "mdi-gradient-horizontal",
@@ -176,6 +208,62 @@ def __init__(self, name):
                                     activator="parent",
                                     location="bottom",
                                 )
+                        elif b.get("nan_menu"):
+                            with html.Div():
+                                with v3.VMenu(
+                                    v_model=f"{name}.show_nan_menu",
+                                    close_on_content_click=True,
+                                    location="bottom",
+                                ):
+                                    with html.Template(v_slot_activator="{ props: nanProps }"):
+                                        btn_kwargs["v_bind"] = "nanProps"
+                                        btn_kwargs["variant"] = "'text'"
+                                        btn_kwargs["color"] = "undefined"
+                                        v3.VBtn(**btn_kwargs)
+                                    with v3.VList(density="compact", max_height="300"):
+                                        for nc in NAN_COLOR_OPTIONS:
+                                            rgba = nc["color"]
+                                            label = nc["situation_preset_type"]
+                                            r255 = int(rgba[0] * 255)
+                                            g255 = int(rgba[1] * 255)
+                                            b255 = int(rgba[2] * 255)
+                                            a_val = rgba[3]
+                                            if a_val == 0:
+                                                swatch_style = (
+                                                    "width:16px; height:16px; "
+                                                    "border-radius:50%; "
+                                                    "border: 1px solid #999; "
+                                                    "margin-right: 8px; "
+                                                    "background: repeating-conic-gradient("
+                                                    "#ccc 0% 25%, #fff 0% 50%) "
+                                                    "50%/8px 8px;"
+                                                )
+                                            else:
+                                                swatch_style = (
+                                                    f"width:16px; height:16px; "
+                                                    f"border-radius:50%; "
+                                                    f"border: 1px solid #999; "
+                                                    f"margin-right: 8px; "
+                                                    f"background: rgb({r255},{g255},{b255});"
+                                                )
+                                            color_json = (
+                                                f"[{rgba[0]},{rgba[1]},{rgba[2]},{rgba[3]}]"
+                                            )
+                                            with v3.VListItem(
+                                                click=(f"{name}.nan_color = {color_json}"),
+                                            ):
+                                                with html.Template(
+                                                    v_slot_prepend=True,
+                                                ):
+                                                    html.Span(
+                                                        style=swatch_style,
+                                                    )
+                                                v3.VListItemTitle(label)
+                                v3.VTooltip(
+                                    text=(b["tip"],),
+                                    activator="parent",
+                                    location="bottom",
+                                )
                         else:
                             btn_kwargs["click"] = b["click"]
                             with html.Div():

tests/test_dataclasses.py

@@ -128,6 +128,16 @@ def test_validation_defaults(self, config):
     def test_active_presets_default_matches(self, config):
         assert config.active_presets == DEFAULT_PRESETS
 
+    def test_nan_color_default(self, config):
+        assert config.nan_color == [0.0, 0.0, 0.0, 0.0]
+
+    def test_show_nan_menu_default(self, config):
+        assert config.show_nan_menu is False
+
+    def test_nan_color_applied_to_ctf_at_init(self, config):
+        assert config._ctf.GetNanColor() == (0.0, 0.0, 0.0)
+        assert config._ctf.GetNanOpacity() == 0.0
+
 
 # =====================================================================
 # Mutation
@@ -568,3 +578,43 @@ def test_no_overlap_sequential_multi_sequential(self):
 
     def test_no_overlap_diverging_cyclic(self):
         assert not (DIVERGING_PRESETS & CYCLIC_PRESETS)
+
+
+# =====================================================================
+# NaN Color
+# =====================================================================
+
+
+class TestNanColor:
+    def test_apply_nan_color_sets_ctf(self, config):
+        config.nan_color = [1.0, 0.0, 1.0, 1.0]
+        config._apply_nan_color()
+        assert config._ctf.GetNanColor() == pytest.approx((1.0, 0.0, 1.0))
+        assert config._ctf.GetNanOpacity() == 1.0
+
+    def test_apply_nan_color_transparent(self, config):
+        config.nan_color = [0.0, 0.0, 0.0, 0.0]
+        config._apply_nan_color()
+        assert config._ctf.GetNanColor() == (0.0, 0.0, 0.0)
+        assert config._ctf.GetNanOpacity() == 0.0
+
+    def test_apply_nan_color_propagates_to_symlog_ctf(self, config):
+        from vtkmodules.vtkRenderingCore import vtkColorTransferFunction
+
+        config._symlog_ctf = vtkColorTransferFunction()
+        config.nan_color = [0.89, 0.10, 0.11, 1.0]
+        config._apply_nan_color()
+        assert config._symlog_ctf.GetNanColor() == pytest.approx((0.89, 0.10, 0.11))
+        assert config._symlog_ctf.GetNanOpacity() == 1.0
+
+    def test_apply_nan_color_handles_short_list(self, config):
+        config.nan_color = [1.0, 0.0]
+        config._apply_nan_color()
+        assert config._ctf.GetNanColor() == (0.0, 0.0, 0.0)
+        assert config._ctf.GetNanOpacity() == 0.0
+
+    def test_apply_nan_color_handles_none(self, config):
+        config.nan_color = None
+        config._apply_nan_color()
+        assert config._ctf.GetNanColor() == (0.0, 0.0, 0.0)
+        assert config._ctf.GetNanOpacity() == 0.0