Merge pull request #15 from Kitware/feature/cut-outside-range

feat: add cut outside range mode (scissors button)

Author: patrickoleary

README.md

@@ -113,7 +113,7 @@ The control panel has three sections, top to bottom:
 
 The toolbar has three areas, left to right:
 
-- **Icon buttons** — Eight buttons separated into three groups by vertical
+- **Icon buttons** — Nine buttons separated into three groups by vertical
   dividers. Active toggles show a primary-colored square outline; the icon
   itself stays black. The NaN color button opens a dropdown instead of
   toggling. Details on each button below.
@@ -140,6 +140,7 @@ The toolbar has three areas, left to right:
 | | | | | |
 | 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. |
+| 9 | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/scissors-cutting.svg" width="24"> | <img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/scissors-cutting.svg" width="24" style="border: 2px solid #1867C0; border-radius: 4px; padding: 2px;"> | Cut Outside Range | Switches between clamp mode (out-of-range values get endpoint color) and cut mode (out-of-range values get NaN color). Disabled unless Custom Range or Δ mode is active. |
 
 Empty rows in the table indicate the vertical separator dividers between
 button groups.
@@ -149,6 +150,8 @@ button groups.
 - **Δ Difference** is disabled when Scale is Log or when Custom Range is on.
   You can always turn Δ Difference *off*.
 - **Custom Range** is disabled when Δ Difference is on.
+- **Cut Outside Range** is disabled when neither Custom Range nor Δ
+  Difference is active.
 - **Category dropdown** is disabled when Δ Difference is on (presets forced
   to Diverging). When Δ is turned off, category resets to Sequential.
 
@@ -171,50 +174,54 @@ on both the main CTF and any render CTF (e.g. symlog).
 
 #### Scale Modes
 
-<table>
-<tr>
-<td width="33%" align="center"><img src="docs/images/clicked-linear.png" width="100%" style="border: 1px solid black;"><br><em>Linear</em></td>
-<td width="33%" align="center"><img src="docs/images/clicked-log.png" width="100%" style="border: 1px solid black;"><br><em>Log</em></td>
-<td width="33%" align="center"><img src="docs/images/clicked-symlog.png" width="100%" style="border: 1px solid black;"><br><em>SymLog</em></td>
-</tr>
-</table>
-
-In all three screenshots, Colorblind Safe, Invert, Custom Range, and
-Discrete are active (outlined). The category is set to Cyclic via the
-dropdown, and the search field contains "V":
-
-- **Category** — Cyclic selected from dropdown; *Preset list* shows only
-  cyclic presets (vikO, brocO, corkO, …).
-- **Colorblind Safe** — Further limits to colorblind-safe cyclic presets.
-- **Invert** — Preset swatches and colorbar render reversed.
-- **Custom Range** — *Settings panel* shows editable **Min** and **Max** fields.
-- **Discrete** — *Settings panel* shows band count. Label adapts: "Colors
-  per tick interval" (Linear) or "Colors per order of magnitude" (Log/SymLog).
-- **Search** — Text field contains "V"; a clear button (✕) appears.
-
-The only difference between the three images is the **Scale** icon, which
-cycles through Linear (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/stairs.svg" width="16">), Log (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/math-log.svg" width="16">), and SymLog (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/sine-wave.svg" width="16">).
-The colorbar tick labels switch between decimal (Linear) and scientific
-notation (Log/SymLog).
+The Scale button cycles through three modes. The colorbar and tick labels
+update to match the active scale:
+
+- **Linear** — evenly spaced ticks, decimal labels. Colorbar image is a
+  direct mapping of the preset. Discrete label reads "Colors per tick
+  interval."
+- **Log** — decade-based ticks, scientific notation labels. Colorbar image
+  is resampled through the log transform so more visual space is given to
+  lower magnitudes. Not available in Δ mode. Discrete label reads "Colors
+  per order of magnitude."
+- **SymLog** — symmetric log around zero, decade ticks adaptively thinned
+  near zero, scientific notation labels. Colorbar image is resampled
+  through the symlog transform. In Δ mode, the epsilon dead zone aligns
+  with the symlog tick marks. Discrete label reads "Colors per order of
+  magnitude."
 
 #### Δ Difference Mode
 
-<table>
-<tr>
-<td width="50%" align="center"><img src="docs/images/clicked-delta-linear.png" width="100%" style="border: 1px solid black;"><br><em>Δ Linear</em></td>
-<td width="50%" align="center"><img src="docs/images/clicked-delta-symlog.png" width="100%" style="border: 1px solid black;"><br><em>Δ SymLog</em></td>
-</tr>
-</table>
+When Δ Difference is active:
 
-When Δ Difference is active (outlined with primary):
-
-- **Preset list** is forced to diverging-only presets (vik shown here).
-- **Scale** only toggles between Linear (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/stairs.svg" width="16">) and SymLog (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/sine-wave.svg" width="16">) — Log is
-  not available.
+- **Preset list** is forced to diverging-only presets.
+- **Scale** only toggles between Linear and SymLog — Log is not available.
 - **Settings panel** replaces Min/Max with **|max|** (symmetric range
   centered at zero) and **ε tolerance** (dead zone around zero).
-- **Custom Range** button is disabled — range is always driven by |max|.
+- **Custom Range** is disabled — range is driven by |max|.
 - **Category** dropdown is disabled — presets locked to Diverging.
+- **Cut Outside Range** is available — out-of-range values can use the
+  NaN color instead of endpoint clamping.
+
+#### Cut Outside Range
+
+The Cut button (<img src="https://cdn.jsdelivr.net/npm/@mdi/svg/svg/scissors-cutting.svg" width="16">)
+toggles between two modes for values outside the color range:
+
+- **Clamp (default)** — out-of-range values are assigned the nearest
+  endpoint color. This is VTK's default behavior.
+- **Cut** — out-of-range values are assigned the NaN color (set via the
+  NaN Color dropdown). With the default transparent NaN color, out-of-range
+  regions become invisible.
+
+Cut mode is only available when **Custom Range** or **Δ Difference** is
+active — these are the modes where the color range may intentionally
+exclude part of the data. When neither is active, the button is disabled
+because the range covers the full data extent.
+
+Internally, cut mode uses `vtkColorTransferFunction.SetUseAboveRangeColor()`
+and `SetUseBelowRangeColor()` with the current NaN color RGB. Changing the
+NaN color automatically updates the above/below range colors.
 
 ## Public API
 
@@ -521,6 +528,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 |
+| `cut_outside_range` | `bool` | `False` | Cut mode: out-of-range values use NaN color instead of endpoint color |
 | `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 |

docs/images/clicked-delta-linear.png

@@ -113,6 +113,7 @@ class ColormapConfig(StateDataModel):
     color_value_min: str = Sync(str, "0")
     color_value_max: str = Sync(str, "1")
     override_range: bool = Sync(bool, False)
+    cut_outside_range: bool = Sync(bool, False)
     diverging: bool = Sync(bool, False)
     epsilon: str = Sync(str, "0")
     abs_max: str = Sync(str, "")
@@ -803,12 +804,30 @@ def _on_nan_color_change(self, nan_color):
         self._apply_nan_color()
         self.mapper_change += 1
 
+    @watch("cut_outside_range", eager=True)
+    def _on_cut_outside_range_change(self, cut_outside_range):
+        """Toggle above/below range color mode on the active CTF(s)."""
+        self._apply_nan_color()
+        self.mapper_change += 1
+
     def _apply_nan_color(self):
-        """Set NaN color (RGBA) on all active CTFs."""
+        """Set NaN color (RGBA) and above/below range colors 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)
+        cut = bool(self.cut_outside_range)
+        for ctf in self._active_ctfs():
+            ctf.SetNanColorRGBA(r, g, b, a)
+            ctf.SetUseAboveRangeColor(cut)
+            ctf.SetUseBelowRangeColor(cut)
+            if cut:
+                ctf.SetAboveRangeColor(r, g, b)
+                ctf.SetBelowRangeColor(r, g, b)
+
+    def _active_ctfs(self):
+        """Return list of active CTFs (main + symlog render CTF if present)."""
+        ctfs = [self._ctf]
         if hasattr(self, "_symlog_ctf") and self._symlog_ctf:
-            self._symlog_ctf.SetNanColorRGBA(r, g, b, a)
+            ctfs.append(self._symlog_ctf)
+        return ctfs

docs/images/clicked-delta-symlog.png

@@ -1,5 +1,5 @@
 :root {
-  --tcmap-editor-size: 360px;
+  --tcmap-editor-size: 420px;
 }
 
 .tcmap-editor {
@@ -24,6 +24,17 @@
   max-width: 120px;
 }
 
+.tcmap-editor-search .v-field__input {
+  padding: 2px 4px;
+  min-height: 0;
+  font-size: 0.8rem;
+}
+
+.tcmap-editor-search .v-field {
+  padding-inline-start: 4px !important;
+  padding-inline-end: 4px !important;
+}
+
 .tcmap-img-preset {
   width: 100%;
   min-width: 20rem;