From 5530aa282045802add780bfa1521269f7440dc3d Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Wed, 28 Oct 2026 12:42:49 +0000 Subject: [PATCH 1/8] moved the code to a clean branch --- .../bhom_tkinter/widgets/cmap_selector.py | 38 ++ .../widgets/drop_down_selection.py | 1 + .../bhom_tkinter/windows/__init__.py | 2 + .../windows/colour_scale_builder.py | 358 +++++++++++ .../src/python_toolkit/plot/colour_scales.py | 571 ++++++++++++++++++ .../Python/tests/test_colour_scale_builder.py | 136 +++++ .../Python/tests/test_colour_scales.py | 184 ++++++ 7 files changed, 1290 insertions(+) create mode 100644 Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py create mode 100644 Python_Engine/Python/src/python_toolkit/plot/colour_scales.py create mode 100644 Python_Engine/Python/tests/test_colour_scale_builder.py create mode 100644 Python_Engine/Python/tests/test_colour_scales.py diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index 4d53594..9165a0f 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py @@ -9,6 +9,8 @@ from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget from python_toolkit.bhom_tkinter.widgets._packing_options import PackingOptions +from python_toolkit.bhom_tkinter.widgets.button import Button +from python_toolkit.plot.colour_scales import ColourScale, ColourScaleLibrary from python_toolkit.bhom.analytics import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.theming.scaling import scale_pad @@ -78,6 +80,7 @@ def __init__( default_cmap: Optional[CmapInput] = None, plot_size: tuple[int, int] = (400, 50), dropdown_position: Literal["n", "e", "s", "w"] = "n", + allow_custom: bool = False, **kwargs ) -> None: """ @@ -98,6 +101,9 @@ def __init__( dropdown_position: Position of the dropdown relative to the preview swatch. "n" = above, "s" = below, "w" = left, "e" = right. + allow_custom: When True, colour scales saved in the + `ColourScaleLibrary` are listed first, and a button opens the + `ColourScaleBuilder` to make a new one. **kwargs: Additional Frame options. """ super().__init__(parent, **kwargs) @@ -166,12 +172,44 @@ def __init__( else: current_colormaps = self._preset_colormaps(self.cmap_set_var.get()) + if allow_custom: + current_colormaps = self._saved_scale_labels(current_colormaps) + current_colormaps + self._populate_cmap_list(current_colormaps) # Resolve default_cmap: may itself be a Colormap object or colour list self._default_label = self._resolve_default_label(default_cmap, current_colormaps) self._select_default_cmap(current_colormaps) + if allow_custom: + self.new_scale_button = Button(header, text="New colour scale...", command=self._open_scale_builder) + self.new_scale_button.pack(side=tk.TOP, anchor=self._pack_anchor, fill="x", pady=(4, 0)) + + def _saved_scale_labels(self, existing: List[str]) -> List[str]: + """Register every saved colour scale as a custom entry and return their labels.""" + labels: List[str] = [] + for scale in ColourScaleLibrary().scales(): + label = self._unique_label(scale.name, existing + labels) + self._custom_cmaps[label] = scale.to_colormap() + labels.append(label) + return labels + + def _open_scale_builder(self) -> None: + """Open the colour scale builder; a saved scale is added to the list and selected.""" + # imported here: the builder window is built from these widgets + from python_toolkit.bhom_tkinter.windows.colour_scale_builder import ColourScaleBuilder + + ColourScaleBuilder(self.winfo_toplevel(), on_save=self._on_scale_saved).run() + + def _on_scale_saved(self, scale: ColourScale) -> None: + existing = list(self.cmap_combobox["values"]) + label = self._unique_label(scale.name, existing) + self._custom_cmaps[label] = scale.to_colormap() + self._populate_cmap_list([label] + existing) + self.colormap_var.set(label) + self._update_cmap_sample() + self._fire_on_change(self.get()) + def _get_all_colormaps(self) -> List[str]: """Return all registered colormap names, including reversed variants. diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py index f5afb4d..47b6083 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py @@ -4,6 +4,7 @@ from tkinter import ttk from typing import Optional, Callable, List, Literal +from python_toolkit.bhom.logging import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget class DropDownSelection(BHoMBaseWidget): diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/__init__.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/__init__.py index cdd1dab..a23d2c0 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/__init__.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/__init__.py @@ -1,4 +1,5 @@ from python_toolkit.bhom_tkinter.bhom_base_child_window import BHoMBaseChildWindow +from .colour_scale_builder import ColourScaleBuilder from .directory_file_selector import DirectoryFileSelector from .landing_page import LandingPage from .modal_window import BHoMModalWindow @@ -8,6 +9,7 @@ __all__ = [ "BHoMBaseChildWindow", "BHoMModalWindow", + "ColourScaleBuilder", "DirectoryFileSelector", "LandingPage", "ProcessingWindow", diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py new file mode 100644 index 0000000..bf2e531 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -0,0 +1,358 @@ +"""Window for building colour scales from the data they will colour. + +Pass the data in and the window shows its distribution, suggests band thresholds, and +lets the user colour, label and save the scale into a named set of the colour scale +library (``python_toolkit.plot.colour_scales``):: + + builder = ColourScaleBuilder(parent, data=room_temperatures, units="degC") + builder.run() + scale = builder.saved_scale # None if closed without saving +""" + +from __future__ import annotations + +import tkinter as tk +from tkinter import ttk +from typing import Callable, Iterable, List, Optional + +import numpy as np +from matplotlib.figure import Figure + +from python_toolkit.bhom.logging import CONSOLE_LOGGER +from python_toolkit.bhom_tkinter.bhom_base_child_window import BHoMBaseChildWindow +from python_toolkit.bhom_tkinter.windows.warning_box import WarningBox +from python_toolkit.bhom_tkinter.widgets._grid_options import GridOptions +from python_toolkit.bhom_tkinter.widgets.button import Button +from python_toolkit.bhom_tkinter.widgets.check_box_selection import CheckboxSelection +from python_toolkit.bhom_tkinter.widgets.colour_picker import ColourPicker +from python_toolkit.bhom_tkinter.widgets.drop_down_selection import DropDownSelection +from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer +from python_toolkit.bhom_tkinter.widgets.label import Label +from python_toolkit.bhom_tkinter.widgets.radio_selection import RadioSelection +from python_toolkit.bhom_tkinter.widgets.spinbox import Spinbox +from python_toolkit.bhom_tkinter.widgets.validated_entry_box import ValidatedEntryBox +from python_toolkit.plot.colour_scales import ( + DEFAULT_SET, + PALETTES, + SUGGESTION_METHODS, + ColourScale, + ColourScaleError, + ColourScaleLibrary, + DataSummary, + GradientScale, + ThresholdScale, + clean_data, + palette_colours, + palette_names, + suggest_thresholds, +) + +THRESHOLDS = "Threshold bands" +GRADIENT = "Gradient" +MAX_BANDS = 12 +ERROR_COLOUR = "#c0392b" + + +class ColourScaleBuilder(BHoMBaseChildWindow): + """Build, preview and save a ThresholdScale or GradientScale against real data.""" + + def __init__( + self, + parent=None, + data: Optional[Iterable] = None, + units: Optional[str] = None, + scale: Optional[ColourScale] = None, + library: Optional[ColourScaleLibrary] = None, + on_save: Optional[Callable[[ColourScale], None]] = None, + palette: Optional[str] = None, + **kwargs, + ): + """ + Args: + parent: Owning window (None for a standalone window). + data: Values the scale will colour; drives the histogram and suggestions. + units: Units of the data, stored with the scale. + scale: An existing scale to edit (saving replaces it). + library: Library to save into (defaults to the user's library). + on_save: Called with the saved scale. + palette: Palette or matplotlib colour map to start from (e.g. the plot's current one). + """ + self.values = clean_data(data) + self.summary = DataSummary.from_data(self.values) if self.values.size else None + self.units = units if units is not None else (scale.units if scale else None) + self.library = library if library is not None else ColourScaleLibrary() + self.editing = scale + self.on_save = on_save + self.saved_scale: Optional[ColourScale] = None + self._band_rows: List[dict] = [] + self._pending = None + self._start_palette = palette + super().__init__( + parent, + title="Colour scale", + submit_text="Save scale", + submit_command=self._save, + close_on_submit=False, + close_text="Close", + modal=parent is not None, + defer_show=True, + resizable=True, + min_width=kwargs.pop("min_width", 620), + min_height=kwargs.pop("min_height", 800), + **kwargs, + ) + self._build_contents() + self.build() + self._load(scale) + + # ── layout ───────────────────────────────────────────────────────────── + + def _build_contents(self) -> None: + frame = self.content_frame + sets = self.library.groups() or [DEFAULT_SET] + default_set = self.editing.group if self.editing else sets[0] + + self.name = ValidatedEntryBox(frame, id="name", helper_text="Name", required=False, width=30, + on_change=lambda _v: self._schedule_preview(), # re-checks, clearing old errors + build_options=GridOptions(row=0, column=0, sticky="w", padx=6, pady=3)) + self.group = DropDownSelection(frame, id="group", helper_text="Set (type a new name to start a set)", + options=sets, default=default_set, state="normal", width=28, + build_options=GridOptions(row=0, column=1, sticky="w", padx=6, pady=3)) + self.kind = RadioSelection(frame, id="kind", fields=[THRESHOLDS, GRADIENT], default=THRESHOLDS, + orient="horizontal", command=lambda _v: self._on_kind_changed(), + build_options=GridOptions(row=1, column=0, columnspan=2, sticky="w", padx=6, pady=3)) + self.data_text = Label(frame, text=self._summary_text(), + build_options=GridOptions(row=2, column=0, columnspan=2, sticky="w", padx=6)) + self.preview = FigureContainer(frame, id="preview", rigid_width=560, rigid_height=130, + build_options=GridOptions(row=3, column=0, columnspan=2, sticky="w", padx=6, pady=4)) + + suggest = ttk.Frame(frame) + suggest.grid(row=5, column=0, columnspan=2, sticky="w", padx=6, pady=3) + self.band_count = Spinbox(suggest, id="bands", helper_text="Bands", values=list(range(2, MAX_BANDS + 1)), + default=5, width=5, build_options=GridOptions(row=0, column=0, sticky="w", padx=(0, 8))) + self.method = DropDownSelection(suggest, id="method", helper_text="Breaks", options=list(SUGGESTION_METHODS), + default="nice", state="readonly", width=10, + build_options=GridOptions(row=0, column=1, sticky="w", padx=(0, 8))) + palettes = palette_names() + self.palette = DropDownSelection(suggest, id="palette", helper_text="Palette / colour map", options=palettes, + default=self._start_palette if self._start_palette in palettes else None, + state="readonly", width=28, command=lambda _v: self._recolour(), + build_options=GridOptions(row=0, column=2, sticky="w", padx=(0, 8))) + self.suggest_button = Button(suggest, text="Suggest from data", command=self._suggest, width=18, + build_options=GridOptions(row=0, column=3, sticky="sw")) + for widget in (self.band_count, self.method, self.palette, self.suggest_button): + widget.build() + if self.summary is None: + self.suggest_button.button.configure(state="disabled") + + self.bands_frame = ttk.Frame(frame) + self.bands_frame.grid(row=6, column=0, columnspan=2, sticky="w", padx=6, pady=3) + self.gradient_frame = ttk.Frame(frame) + self.gradient_frame.grid(row=6, column=0, columnspan=2, sticky="w", padx=6, pady=3) + self.reverse = CheckboxSelection(self.gradient_frame, id="reverse", fields=["Reverse"], + command=lambda _v: self._schedule_preview(), + build_options=GridOptions(row=0, column=0, sticky="w", padx=(0, 12))) + self.steps = Spinbox(self.gradient_frame, id="steps", helper_text="Steps (0 = smooth)", + values=[0] + list(range(2, 21)), default=0, width=5, + command=lambda _v: self._schedule_preview(), + build_options=GridOptions(row=0, column=1, sticky="w")) + self.reverse.build() + self.steps.build() + + self.status = Label(frame, text="", foreground=ERROR_COLOUR, wraplength=560, justify="left", + build_options=GridOptions(row=4, column=0, columnspan=2, sticky="w", padx=6)) + self.widgets = [self.name, self.group, self.kind, self.data_text, self.preview, self.status] + + def _summary_text(self) -> str: + if self.summary is None: + return "No data passed in: set the thresholds by hand." + s = self.summary + units = f" {self.units}" if self.units else "" + return (f"{s.count} values from {s.minimum:.4g} to {s.maximum:.4g}{units}; " + f"median {s.quartiles[1]:.4g}, middle half {s.quartiles[0]:.4g} to {s.quartiles[2]:.4g}") + + # ── state ────────────────────────────────────────────────────────────── + + def _load(self, scale: Optional[ColourScale]) -> None: + if isinstance(scale, GradientScale): + self.name.set(scale.name) + self.kind.set(GRADIENT) + self.steps.set(scale.bins or 0) + elif isinstance(scale, ThresholdScale): + self.name.set(scale.name) + self._set_bands(scale.thresholds, scale.colours, scale.labels) + elif self.summary is not None: + self.name.set(self._unused_name("New scale")) + self._suggest() + else: + self.name.set(self._unused_name("New scale")) + self._set_bands([1.0, 2.0], palette_colours(self.palette.get(), 3), None) + self._on_kind_changed() + + def _on_kind_changed(self) -> None: + threshold = self.kind.get() == THRESHOLDS + if threshold: + self.gradient_frame.grid_remove() + self.bands_frame.grid() + else: + self.bands_frame.grid_remove() + self.gradient_frame.grid() + self._schedule_preview() + + def _suggest(self) -> None: + try: + bands = int(self.band_count.get()) + thresholds = suggest_thresholds(self.values, bands, self.method.get()) + except (ColourScaleError, ValueError) as e: + self.status.set(str(e)) + return + self._set_bands(thresholds, palette_colours(self.palette.get(), len(thresholds) + 1), None) + + def _recolour(self) -> None: + """A new palette recolours the bands, keeping their thresholds and labels.""" + if not self._band_rows: + return + for row, colour in zip(self._band_rows, palette_colours(self.palette.get(), len(self._band_rows))): + row["colour"].set(colour) + self._schedule_preview() + + def _set_bands(self, thresholds, colours, labels) -> None: + for child in self.bands_frame.winfo_children(): + child.destroy() + self._band_rows = [] + n = len(colours) + headers = ("Colour", "Label (legend)", "From", "Up to") + for col, text in enumerate(headers): + ttk.Label(self.bands_frame, text=text, style="Caption.TLabel").grid(row=0, column=col, sticky="w", padx=4) + for i in range(n): + picker = ColourPicker(self.bands_frame, default_colour=colours[i], swatch_width=36, swatch_height=20, + command=lambda _c: self._schedule_preview()) + picker.grid(row=i + 1, column=0, sticky="nw", padx=4, pady=(6, 0)) + label = ValidatedEntryBox(self.bands_frame, required=False, width=22, + on_change=lambda _v: self._schedule_preview()) + label.grid(row=i + 1, column=1, sticky="w", padx=4) + label.set((labels[i] or "") if labels else "") + lower = ttk.Label(self.bands_frame, text="") + lower.grid(row=i + 1, column=2, sticky="nw", padx=4, pady=(6, 0)) + upper = None + if i < n - 1: + upper = ValidatedEntryBox(self.bands_frame, required=False, width=10, + on_change=lambda _v: self._schedule_preview()) + upper.grid(row=i + 1, column=3, sticky="w", padx=4) + upper.set(f"{thresholds[i]:.6g}") + else: + ttk.Label(self.bands_frame, text="and above").grid(row=i + 1, column=3, sticky="nw", padx=4, pady=(6, 0)) + self._band_rows.append({"colour": picker, "label": label, "lower": lower, "upper": upper}) + self.band_count.set(n) + self._schedule_preview() + + def current_scale(self) -> ColourScale: + """The scale described by the window right now (raises ColourScaleError if invalid).""" + name = (self.name.get() or "").strip() + group = (self.group.get() or "").strip() or DEFAULT_SET + if self.kind.get() == GRADIENT: + name = self.palette.get() + colours = PALETTES.get(name) or palette_colours(name, 9) + if self.reverse.get(): + colours = colours[::-1] + n = len(colours) + steps = int(self.steps.get() or 0) + return GradientScale(name, [(i / (n - 1), c) for i, c in enumerate(colours)], relative=True, + bins=steps or None, units=self.units, group=group) + thresholds = [] + for i, row in enumerate(self._band_rows[:-1]): + text = (row["upper"].get() or "").strip() + try: + thresholds.append(float(text)) + except ValueError: + raise ColourScaleError(f"Band {i + 1}: '{text}' is not a number.") from None + colours = [row["colour"].get() for row in self._band_rows] + labels = [(row["label"].get() or "").strip() or None for row in self._band_rows] + return ThresholdScale(name, thresholds, colours, labels=labels if any(labels) else None, + units=self.units, group=group) + + def _unused_name(self, base: str) -> str: + names = set(self.library.names()) + n = 1 + name = base + while name in names: + n += 1 + name = f"{base} {n}" + return name + + def _save(self) -> None: + """Validate, save to the library and close; errors are shown in a pop-up and stay in the window.""" + try: + scale = self.current_scale() + self.library.save(scale, overwrite=self.editing is not None and self.editing.name == scale.name) + except (ColourScaleError, OSError) as e: + message = str(e) + if "already exists" in message: + message += " Give this scale another name, or edit the saved one instead." + self.status.set(message) + box = WarningBox(title="Scale not saved", errors=[message], parent=self) + box.build() + box.run() + return + CONSOLE_LOGGER.info(f"Saved colour scale '{scale.name}' in set '{scale.group}'.") + self.saved_scale = scale + if self.on_save is not None: + self.on_save(scale) + self.destroy_root() + + # ── preview ──────────────────────────────────────────────────────────── + + def _schedule_preview(self) -> None: + if self._pending is not None: + try: + self.after_cancel(self._pending) + except tk.TclError: + pass + self._pending = self.after(250, self._update_preview) + + def _update_preview(self) -> None: + self._pending = None + try: + scale = self.current_scale() + except ColourScaleError as e: + self.status.set(str(e)) + return + self.status.set("") + if isinstance(scale, ThresholdScale): + for row, (lower, _upper) in zip(self._band_rows, scale.band_ranges()): + row["lower"].configure(text="below" if lower is None else f"{lower:.6g}") + self.preview.embed_figure(preview_figure(scale, self.values, self.summary)) + + +def preview_figure(scale: ColourScale, values: np.ndarray, summary: Optional[DataSummary]) -> Figure: + """Histogram of the data over the scale's colours (or the colours alone without data).""" + fig = Figure(figsize=(5.6, 1.3), dpi=100) + ax = fig.add_axes([0.04, 0.2, 0.94, 0.76]) + sample = values if values.size else scale.preview_data() + mapping = scale.mapping(sample) + lo, hi = (summary.minimum, summary.maximum) if summary else (float(sample.min()), float(sample.max())) + if lo == hi: + lo, hi = lo - 0.5, hi + 0.5 + pad = (hi - lo) * 0.04 + xs = np.linspace(lo - pad, hi + pad, 400) + colours = mapping.cmap(mapping.norm(xs)) + ax.imshow(colours[np.newaxis, :, :], aspect="auto", extent=(xs[0], xs[-1], 0, 1), alpha=0.85, + origin="lower", zorder=0) + if summary is not None: + counts, edges = summary.histogram + heights = counts / max(counts.max(), 1) + ax.bar(edges[:-1], heights, width=np.diff(edges), align="edge", color="#202020", alpha=0.55, + edgecolor="#ffffff", linewidth=0.6, zorder=1) + if isinstance(scale, ThresholdScale): + for t in scale.thresholds: + if xs[0] <= t <= xs[-1]: + ax.axvline(t, color="#000000", linewidth=1.2, zorder=2) + ax.set_xlim(xs[0], xs[-1]) + ax.set_ylim(0, 1.05) + ax.set_yticks([]) + ax.tick_params(labelsize=7) + for side in ("top", "right", "left"): + ax.spines[side].set_visible(False) + return fig + + diff --git a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py new file mode 100644 index 0000000..a034516 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py @@ -0,0 +1,571 @@ +"""Colour scales defined in data units, with user-defined sets saved for reuse. + +A matplotlib Colormap only knows positions from 0 to 1, so a saved "18 / 21 / 24 degC" band +set drifts whenever the data range changes. A ColourScale keeps its definition in data +units and produces the matching (Colormap, Normalize) pair for whatever data is passed in: + + scale = ThresholdScale("Comfort", thresholds=[18, 21, 24], + colours=["#3b4cc0", "#8db0fe", "#f4987a", "#b40426"], + labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") + mapping = scale.mapping(room_temperatures) # pass the data in + ax.scatter(x, y, c=room_temperatures, cmap=mapping.cmap, norm=mapping.norm) + +Scales can be suggested from the data (equal interval, quantile, or rounded "nice" breaks), +and are saved in a ColourScaleLibrary under named sets (e.g. "TM59", "Part L"). +""" + +from __future__ import annotations + +import json +import math +from abc import ABC, abstractmethod +from dataclasses import dataclass, field +from pathlib import Path +from typing import Any, ClassVar, Dict, Iterable, List, Optional, Sequence, Tuple, Type + +import numpy as np +from matplotlib import colormaps +from matplotlib.colors import ( + BoundaryNorm, + Colormap, + LinearSegmentedColormap, + ListedColormap, + Normalize, + to_hex, + to_rgba, +) + +from python_toolkit.bhom.logging import CONSOLE_LOGGER + +LIBRARY_FILE = Path.home() / ".bhom" / "colour_scales.json" +LIBRARY_VERSION = 1 +DEFAULT_SET = "My scales" + +# Preset palettes for building scales (colour-blind safe sets first). +PALETTES: Dict[str, List[str]] = { + "Okabe-Ito (colour-blind safe)": ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"], + "Viridis (colour-blind safe)": ["#440154", "#3b528b", "#21918c", "#5ec962", "#fde725"], + "Cividis (colour-blind safe)": ["#00204c", "#31446b", "#666870", "#988e5d", "#ffe945"], + "Cool to warm": ["#3b4cc0", "#8db0fe", "#dddddd", "#f4987a", "#b40426"], + "Traffic light": ["#1a9850", "#fee08b", "#d73027"], + "LTC Heatmap": ["#000004", "#51127c", "#b63679", "#fb8861", "#fcffa4"], + "LTC Maya": ["#5c8286", "#a1b18c", "#e7cca6", "#d98f79", "#b35b5a"], + "LTC Paloma": ["#1a2a40", "#456a73", "#82a69d", "#d9ccb6", "#bf8865"], +} + +# Palettes registered as matplotlib colour maps (with _r), so every colour map list offers them. +# Viridis and Cividis are already matplotlib maps. +PALETTE_CMAPS: Dict[str, str] = { + "Okabe-Ito (colour-blind safe)": "okabe_ito", + "Cool to warm": "cool_to_warm", + "Traffic light": "traffic_light", + "LTC Heatmap": "ltc_heatmap", + "LTC Maya": "ltc_maya", + "LTC Paloma": "ltc_paloma", +} + +SUGGESTION_METHODS = ("equal", "quantile", "nice") + + +class ColourScaleError(ValueError): + """A colour scale definition, or the saved library, is invalid.""" + + +# --------------------------------------------------------------------------- +# Data passed in +# --------------------------------------------------------------------------- + +def clean_data(data: Optional[Iterable]) -> np.ndarray: + """Finite float values from any iterable; None, NaN and non-numbers are dropped.""" + if data is None: + return np.empty(0) + numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) + return numbers[np.isfinite(numbers)] + + +@dataclass(frozen=True) +class DataSummary: + """What a scale needs to know about the data: range, spread and distribution.""" + + count: int + minimum: float + maximum: float + mean: float + quartiles: Tuple[float, float, float] + histogram: Tuple[np.ndarray, np.ndarray] # (counts, bin edges) + + @classmethod + def from_data(cls, data: Iterable, bins: int = 30) -> "DataSummary": + values = clean_data(data) + if values.size == 0: + raise ColourScaleError("No numeric values in the data passed in.") + lo, hi = float(values.min()), float(values.max()) + if lo == hi: + lo, hi = lo - 0.5, hi + 0.5 + counts, edges = np.histogram(values, bins=bins, range=(lo, hi)) + q1, q2, q3 = (float(q) for q in np.quantile(values, [0.25, 0.5, 0.75])) + return cls(int(values.size), float(values.min()), float(values.max()), float(values.mean()), + (q1, q2, q3), (counts, edges)) + + +def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List[float]: + """Inner boundaries splitting the data into `bands` bands. + + equal: equal-width bands across the data range + quantile: roughly the same number of values in each band + nice: equal-width bands on rounded 1 / 2 / 5 x 10^n steps + """ + if bands < 2: + raise ColourScaleError("A threshold scale needs at least 2 bands.") + if method not in SUGGESTION_METHODS: + raise ColourScaleError(f"Method must be one of {SUGGESTION_METHODS}, not '{method}'.") + values = clean_data(data) + if values.size == 0: + raise ColourScaleError("No numeric values to suggest thresholds from.") + lo, hi = float(values.min()), float(values.max()) + if lo == hi: + return [lo + i for i in range(1, bands)] + + if method == "equal": + return [float(v) for v in np.linspace(lo, hi, bands + 1)[1:-1]] + if method == "quantile": + cuts = np.quantile(values, np.linspace(0, 1, bands + 1)[1:-1]) + unique = sorted(set(float(c) for c in cuts)) + if len(unique) < bands - 1: + raise ColourScaleError("Too many repeated values for that many quantile bands; use fewer bands.") + return unique + + return _nice_thresholds(lo, hi, bands - 1) + + +def _nice_thresholds(lo: float, hi: float, wanted: int) -> List[float]: + """Rounded breaks (multiples of 1, 2, 2.5 or 5 x 10^n) strictly inside the data range. + + Picks the step whose breaks come closest to `wanted`, then keeps the middle `wanted` + of them, so every band contains data rather than extending beyond it.""" + raw = (hi - lo) / (wanted + 1) + exponent = math.floor(math.log10(raw)) + best = None + for power in (exponent - 1, exponent, exponent + 1): + for factor in (1, 2, 2.5, 5): + step = factor * 10 ** power + first, last = math.floor(lo / step) + 1, math.ceil(hi / step) - 1 + inner = [round(k * step, 10) for k in range(first, last + 1)] + if not inner: + continue + score = abs(len(inner) - wanted) + (0.5 if factor == 2.5 else 0.0) # prefer rounder steps + if best is None or score < best[0]: + best = (score, inner) + if best is None: # range too narrow for rounded breaks + return [float(v) for v in np.linspace(lo, hi, wanted + 2)[1:-1]] + inner = best[1] + if len(inner) > wanted: + start = (len(inner) - wanted) // 2 + inner = inner[start:start + wanted] + return inner + + +def register_palette_cmaps() -> None: + """Add the preset palettes to matplotlib's colour maps (idempotent).""" + for palette, name in PALETTE_CMAPS.items(): + if name not in colormaps: + cmap = LinearSegmentedColormap.from_list(name, PALETTES[palette]) + colormaps.register(cmap, name=name) + colormaps.register(cmap.reversed(), name=f"{name}_r") + + +def palette_names() -> List[str]: + """Preset palettes first, then every matplotlib colour map (no reversed copies).""" + preset = set(PALETTE_CMAPS.values()) + return list(PALETTES) + sorted((n for n in colormaps if not n.endswith("_r") and n not in preset), key=str.lower) + + +def palette_colours(palette: str, count: int) -> List[str]: + """`count` colours sampled evenly from a preset palette or a matplotlib colour map.""" + if palette in PALETTES: + cmap = LinearSegmentedColormap.from_list(palette, PALETTES[palette]) + elif palette in colormaps: + cmap = colormaps[palette] + else: + raise ColourScaleError(f"Unknown palette or colour map '{palette}'.") + if count == 1: + return [to_hex(cmap(0.5))] + return [to_hex(cmap(i / (count - 1))) for i in range(count)] + + +# --------------------------------------------------------------------------- +# Scales +# --------------------------------------------------------------------------- + +@dataclass +class ScaleMapping: + """Everything a plot needs to colour values with a scale.""" + + cmap: Colormap + norm: Normalize + ticks: List[float] + tick_labels: List[str] + band_labels: Optional[List[str]] = None # threshold scales: one per band, for legends + + def colours_for(self, values: Iterable) -> np.ndarray: + """RGBA per value (NaN for values that cannot be read).""" + data = np.array([_to_float(v) for v in values], dtype=float) + out = np.full((data.size, 4), np.nan) + ok = np.isfinite(data) + if ok.any(): + out[ok] = self.cmap(self.norm(data[ok])) + return out + + +class ColourScale(ABC): + """Base class: a named colour scale defined in data units. + + Subclasses produce a ScaleMapping from the data passed in, and round-trip through + plain dicts so they can be saved. `group` is the user-defined set the scale belongs to. + """ + + kind: ClassVar[str] = "" + _registry: ClassVar[Dict[str, Type["ColourScale"]]] = {} + + def __init__(self, name: str, units: Optional[str] = None, description: str = "", + group: str = DEFAULT_SET): + self.name = validate_name(name) + self.units = units + self.description = description + self.group = group or DEFAULT_SET + + def __init_subclass__(cls, **kwargs): + super().__init_subclass__(**kwargs) + if cls.kind: + ColourScale._registry[cls.kind] = cls + + @abstractmethod + def mapping(self, data: Optional[Iterable] = None) -> ScaleMapping: + """Colormap and normaliser for this scale, fitted to `data` where the scale is relative.""" + + @abstractmethod + def _definition(self) -> Dict[str, Any]: + """Subclass-specific fields for to_dict.""" + + def to_dict(self) -> Dict[str, Any]: + return {"type": self.kind, "name": self.name, "units": self.units, + "description": self.description, "group": self.group, **self._definition()} + + @classmethod + def from_dict(cls, data: Dict[str, Any]) -> "ColourScale": + kind = data.get("type") + scale_cls = ColourScale._registry.get(kind) + if scale_cls is None: + raise ColourScaleError(f"Unknown colour scale type '{kind}'.") + return scale_cls._from_definition(data) + + @classmethod + @abstractmethod + def _from_definition(cls, data: Dict[str, Any]) -> "ColourScale": + """Build from a dict written by to_dict.""" + + def preview_data(self) -> np.ndarray: + """Representative values spanning the scale, for swatches without real data.""" + return np.linspace(0.0, 1.0, 11) + + def to_colormap(self, data: Optional[Iterable] = None, samples: int = 256) -> Colormap: + """A plain 0-1 colormap that looks like this scale across its range (band widths kept), + for widgets that only take a Colormap. Plots should use `mapping`, which keeps data units.""" + mapping = self.mapping(data if data is not None else self.preview_data()) + values = np.linspace(mapping.norm.vmin, mapping.norm.vmax, samples) + return ListedColormap(mapping.cmap(mapping.norm(values)), name=self.name) + + def __repr__(self) -> str: + return f"{type(self).__name__}({self.name!r}, set={self.group!r})" + + +class GradientScale(ColourScale): + """A continuous gradient through colour stops. + + Stop positions are either absolute data values, or relative (0 = data minimum, + 1 = data maximum) so the gradient stretches to whatever data is passed in. + """ + + kind = "gradient" + + def __init__(self, name: str, stops: Sequence[Tuple[float, str]], relative: bool = True, + bins: Optional[int] = None, **kwargs): + super().__init__(name, **kwargs) + if len(stops) < 2: + raise ColourScaleError("A gradient needs at least 2 colour stops.") + self.stops = sorted(((float(p), _hex(c)) for p, c in stops), key=lambda s: s[0]) + self.relative = bool(relative) + self.bins = bins # None for smooth, or a number of discrete steps + positions = [p for p, _ in self.stops] + if positions[0] == positions[-1]: + raise ColourScaleError("Gradient stops must span a range.") + if self.relative and (positions[0] < 0 or positions[-1] > 1): + raise ColourScaleError("Relative stop positions must lie between 0 and 1.") + + @classmethod + def from_palette(cls, name: str, palette: str, **kwargs) -> "GradientScale": + if palette not in PALETTES: + raise ColourScaleError(f"Unknown palette '{palette}'.") + colours = PALETTES[palette] + n = len(colours) + return cls(name, [(i / (n - 1), c) for i, c in enumerate(colours)], relative=True, **kwargs) + + def value_range(self, data: Optional[Iterable] = None) -> Tuple[float, float]: + if not self.relative: + return self.stops[0][0], self.stops[-1][0] + values = clean_data(data) + if values.size == 0: + return 0.0, 1.0 + lo, hi = float(values.min()), float(values.max()) + return (lo - 0.5, hi + 0.5) if lo == hi else (lo, hi) + + def mapping(self, data: Optional[Iterable] = None) -> ScaleMapping: + vmin, vmax = self.value_range(data) + first, last = self.stops[0][0], self.stops[-1][0] + nodes = [((p - first) / (last - first), c) for p, c in self.stops] + cmap = LinearSegmentedColormap.from_list(self.name, nodes) + if self.bins: + cmap = cmap.resampled(int(self.bins)) + edges = list(np.linspace(vmin, vmax, int(self.bins) + 1)) + norm = BoundaryNorm(edges, ncolors=int(self.bins), clip=True) + ticks = edges + else: + norm = Normalize(vmin=vmin, vmax=vmax, clip=True) + ticks = list(np.linspace(vmin, vmax, 6)) + return ScaleMapping(cmap, norm, ticks, [_fmt(t) for t in ticks]) + + def _definition(self) -> Dict[str, Any]: + return {"stops": [[p, c] for p, c in self.stops], "relative": self.relative, "bins": self.bins} + + @classmethod + def _from_definition(cls, data: Dict[str, Any]) -> "GradientScale": + return cls(data["name"], [tuple(s) for s in data["stops"]], relative=data.get("relative", True), + bins=data.get("bins"), units=data.get("units"), description=data.get("description", ""), + group=data.get("group") or DEFAULT_SET) + + +class ThresholdScale(ColourScale): + """Bands with fixed boundaries in data units: one colour (and optional label) per band. + + `thresholds` are the inner boundaries; values below the first threshold take the first + colour and values at or above the last take the last, so the bands hold for any data. + """ + + kind = "thresholds" + + def __init__(self, name: str, thresholds: Sequence[float], colours: Sequence[str], + labels: Optional[Sequence[Optional[str]]] = None, **kwargs): + super().__init__(name, **kwargs) + self.thresholds = [float(t) for t in thresholds] + self.colours = [_hex(c) for c in colours] + if not self.thresholds: + raise ColourScaleError("A threshold scale needs at least one threshold.") + if any(b <= a for a, b in zip(self.thresholds, self.thresholds[1:])): + raise ColourScaleError("Thresholds must be strictly increasing.") + if len(self.colours) != len(self.thresholds) + 1: + raise ColourScaleError( + f"{len(self.thresholds)} threshold(s) make {len(self.thresholds) + 1} bands, " + f"but {len(self.colours)} colour(s) were given.") + if labels is not None and len(labels) != len(self.colours): + raise ColourScaleError(f"Give one label per band ({len(self.colours)}), or none.") + self.labels = [None if not l else str(l) for l in labels] if labels is not None else None + + @classmethod + def from_data(cls, name: str, data: Iterable, bands: int = 5, method: str = "nice", + palette: str = "Viridis (colour-blind safe)", **kwargs) -> "ThresholdScale": + """Suggest thresholds from the data passed in, coloured from a preset palette.""" + thresholds = suggest_thresholds(data, bands, method) + return cls(name, thresholds, palette_colours(palette, len(thresholds) + 1), **kwargs) + + @property + def bands(self) -> int: + return len(self.colours) + + def band_ranges(self) -> List[Tuple[Optional[float], Optional[float]]]: + """(lower, upper) per band; None for the open ends.""" + edges: List[Optional[float]] = [None] + list(self.thresholds) + [None] + return list(zip(edges[:-1], edges[1:])) + + def band_labels(self) -> List[str]: + """Labels as given, else ranges such as '< 18', '18 - 21', '>= 24'.""" + auto = [] + for lower, upper in self.band_ranges(): + if lower is None: + auto.append(f"< {_fmt(upper)}") + elif upper is None: + auto.append(f">= {_fmt(lower)}") + else: + auto.append(f"{_fmt(lower)} - {_fmt(upper)}") + if self.labels is None: + return auto + return [given or default for given, default in zip(self.labels, auto)] + + def band_of(self, value: float) -> int: + """Index of the band a value falls in.""" + return int(np.searchsorted(self.thresholds, float(value), side="right")) + + def mapping(self, data: Optional[Iterable] = None) -> ScaleMapping: + values = clean_data(data) + span = self.thresholds[-1] - self.thresholds[0] or 1.0 + lo = min(self.thresholds[0] - span / max(self.bands - 2, 1), float(values.min()) if values.size else math.inf) + hi = max(self.thresholds[-1] + span / max(self.bands - 2, 1), float(values.max()) if values.size else -math.inf) + edges = [lo] + self.thresholds + [hi + 1e-9] + cmap = ListedColormap(self.colours, name=self.name) + norm = BoundaryNorm(edges, ncolors=self.bands, clip=True) + return ScaleMapping(cmap, norm, list(self.thresholds), [_fmt(t) for t in self.thresholds], + band_labels=self.band_labels()) + + def preview_data(self) -> np.ndarray: + span = self.thresholds[-1] - self.thresholds[0] or 1.0 + pad = span / max(self.bands - 2, 1) + return np.linspace(self.thresholds[0] - pad, self.thresholds[-1] + pad, 101) + + def _definition(self) -> Dict[str, Any]: + return {"thresholds": self.thresholds, "colours": self.colours, "labels": self.labels} + + @classmethod + def _from_definition(cls, data: Dict[str, Any]) -> "ThresholdScale": + return cls(data["name"], data["thresholds"], data["colours"], labels=data.get("labels"), + units=data.get("units"), description=data.get("description", ""), + group=data.get("group") or DEFAULT_SET) + + +# --------------------------------------------------------------------------- +# Library: saved scales grouped in user-defined sets +# --------------------------------------------------------------------------- + +class ColourScaleLibrary: + """Saved colour scales, grouped into named sets, stored as JSON. + + Entries that cannot be read are kept on disk, reported in `problems` and logged, + never silently dropped. + """ + + def __init__(self, path: Optional[Path] = None): + self.path = Path(path) if path is not None else LIBRARY_FILE + self.problems: List[str] = [] + self._scales: Dict[str, ColourScale] = {} + self._unreadable: List[Dict[str, Any]] = [] + self.reload() + + def reload(self) -> None: + self._scales.clear() + self._unreadable.clear() + self.problems = [] + if not self.path.exists(): + return + try: + raw = json.loads(self.path.read_text(encoding="utf-8")) + except (OSError, ValueError) as e: + raise ColourScaleError(f"Cannot read the colour scale library {self.path}: {e}") from e + + entries = raw.get("scales", []) if isinstance(raw, dict) else raw + if not isinstance(entries, list): + raise ColourScaleError(f"{self.path} is not a colour scale library.") + for entry in entries: + try: + scale = ColourScale.from_dict(entry) + except (KeyError, TypeError, ValueError) as e: + name = entry.get("name", "?") if isinstance(entry, dict) else "?" + self.problems.append(f"Could not read saved scale '{name}': {e}") + self._unreadable.append(entry) + continue + self._scales[scale.name] = scale + for problem in self.problems: + CONSOLE_LOGGER.warning(problem) + + # -- queries ------------------------------------------------------------ + + def names(self, group: Optional[str] = None) -> List[str]: + return [s.name for s in self._scales.values() if group is None or s.group == group] + + def groups(self) -> List[str]: + """The user-defined sets, in first-seen order.""" + return list(dict.fromkeys(s.group for s in self._scales.values())) + + def scales(self, group: Optional[str] = None) -> List[ColourScale]: + return [s for s in self._scales.values() if group is None or s.group == group] + + def get(self, name: str) -> ColourScale: + if name not in self._scales: + raise KeyError(f"No saved colour scale named '{name}'.") + return self._scales[name] + + def __contains__(self, name: str) -> bool: + return name in self._scales + + def __len__(self) -> int: + return len(self._scales) + + # -- changes ------------------------------------------------------------ + + def save(self, scale: ColourScale, overwrite: bool = False) -> None: + if scale.name in self._scales and not overwrite: + raise ColourScaleError(f"A scale named '{scale.name}' already exists.") + self._scales[scale.name] = scale + self._write() + + def delete(self, name: str) -> None: + if name not in self._scales: + raise KeyError(f"No saved colour scale named '{name}'.") + del self._scales[name] + self._write() + + def rename_group(self, old: str, new: str) -> None: + for scale in self.scales(old): + scale.group = new + self._write() + + def delete_group(self, group: str) -> None: + for name in self.names(group): + del self._scales[name] + self._write() + + def clear(self) -> None: + self._scales.clear() + self._write() + + def _write(self) -> None: + self.path.parent.mkdir(parents=True, exist_ok=True) + payload = {"version": LIBRARY_VERSION, + "scales": [s.to_dict() for s in self._scales.values()] + self._unreadable} + tmp = self.path.with_suffix(".tmp") + tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8") + tmp.replace(self.path) + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + +_INVALID_NAME_CHARS = set(r'\/:*?"<>|') + + +def validate_name(name: str) -> str: + name = (name or "").strip() + if not name: + raise ColourScaleError("A colour scale needs a name.") + if any(c in _INVALID_NAME_CHARS for c in name): + raise ColourScaleError("Names cannot contain \\ / : * ? \" < > |") + return name + + +def _hex(colour: str) -> str: + try: + return to_hex(to_rgba(colour)) + except ValueError as e: + raise ColourScaleError(f"'{colour}' is not a colour.") from e + + +def _to_float(value) -> float: + try: + return float(value) + except (TypeError, ValueError): + return math.nan + + +def _fmt(value: float) -> str: + return f"{value:.4g}" + + +register_palette_cmaps() diff --git a/Python_Engine/Python/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py new file mode 100644 index 0000000..5a80508 --- /dev/null +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -0,0 +1,136 @@ +import numpy as np +import pytest + +from python_toolkit.bhom_tkinter.bhom_base_window import BHoMBaseWindow +from python_toolkit.bhom_tkinter.widgets.cmap_selector import CmapSelector +from python_toolkit.bhom_tkinter.windows import ColourScaleBuilder +from python_toolkit.bhom_tkinter.windows.colour_scale_builder import GRADIENT, preview_figure +from python_toolkit.plot.colour_scales import ColourScaleLibrary, DataSummary, GradientScale, ThresholdScale + + +@pytest.fixture(scope="module") +def host(): + """One Tk root for the module: creating a Tk root per test intermittently fails to start Tcl on Windows.""" + root = BHoMBaseWindow(title="Builder host", show_submit=False, show_close=False) + root.withdraw() + yield root + root.destroy_root() + + +@pytest.fixture(autouse=True) +def warnings_shown(monkeypatch): + """Record warning pop-ups instead of blocking on them.""" + from python_toolkit.bhom_tkinter.windows import colour_scale_builder + + shown = [] + + class _Box: + def __init__(self, title, errors, parent=None): + shown.append(errors) + + def build(self): + pass + + def run(self): + pass + + monkeypatch.setattr(colour_scale_builder, "WarningBox", _Box) + return shown + + +@pytest.fixture +def library(tmp_path): + return ColourScaleLibrary(tmp_path / "scales.json") + + +def test_builder_suggests_bands_from_data(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), units="degC", library=library) + scale = builder.current_scale() + assert isinstance(scale, ThresholdScale) + assert scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + assert scale.units == "degC" + assert "200 values from 16 to 30 degC" in builder.data_text.get() + + +def test_builder_saves_labels_into_a_set(host, library): + saved = [] + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library=library, on_save=saved.append) + builder.name.set("Comfort") + builder.group.value_var.set("Overheating") # typed into the editable set box + builder._band_rows[0]["label"].set("Cold") + builder._save() + reopened = ColourScaleLibrary(library.path) + scale = reopened.get("Comfort") + assert saved and saved[0].name == "Comfort" + assert scale.group == "Overheating" and scale.band_labels()[0] == "Cold" + + +def test_builder_reports_bad_thresholds_without_saving(host, library, warnings_shown): + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library=library) + builder._band_rows[0]["upper"].set("warm") + builder._save() + assert builder.saved_scale is None and "not a number" in builder.status.get() + assert warnings_shown and "not a number" in warnings_shown[0][0] # shown in a pop-up, not only in the window + assert len(library) == 0 + + +def test_builder_name_clash_is_explained_and_default_names_are_free(host, library, warnings_shown): + library.save(ThresholdScale("New scale", [1, 2], ["#000000", "#808080", "#ffffff"])) + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library=library) + assert builder.name.get() == "New scale 2" + builder.name.set("New scale") + builder._save() + assert builder.saved_scale is None and "another name" in warnings_shown[-1][0] + builder.name.set("Renamed") + builder._update_preview() # what the name change schedules + assert builder.status.get() == "" # the old error does not linger + + +def test_builder_gradient_and_edit(host, library): + builder = ColourScaleBuilder(host, data=[0, 1, 2], library=library) + builder.kind.set(GRADIENT) + builder._on_kind_changed() + assert isinstance(builder.current_scale(), GradientScale) + existing = ThresholdScale("Existing", [1, 2], ["#000000", "#808080", "#ffffff"], labels=["a", "b", "c"]) + editor = ColourScaleBuilder(host, scale=existing, library=library) + assert editor.current_scale().band_labels() == ["a", "b", "c"] + + +def test_preview_with_and_without_data(): + scale = ThresholdScale("T", [20, 25], ["#0000ff", "#00ff00", "#ff0000"]) + values = np.linspace(16, 30, 50) + assert preview_figure(scale, values, DataSummary.from_data(values)).axes + assert preview_figure(scale, np.array([]), None).axes + + +def test_builder_starts_from_a_colour_map_and_recolours(host, library): + from python_toolkit.plot.colour_scales import palette_colours + + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 50), library=library, palette="magma") + assert builder.palette.get() == "magma" + assert [r["colour"].get() for r in builder._band_rows] == palette_colours("magma", 5) + builder.palette.set("Traffic light") + builder._recolour() + scale = builder.current_scale() + assert scale.colours == palette_colours("Traffic light", 5) and scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + + +def test_cmap_selector_lists_saved_scales_and_adds_new_ones(host, tmp_path, monkeypatch): + from python_toolkit.plot import colour_scales + + monkeypatch.setattr(colour_scales, "LIBRARY_FILE", tmp_path / "scales.json") + ColourScaleLibrary().save(ThresholdScale("Comfort", [18, 24], ["#0000ff", "#00ff00", "#ff0000"])) + selector = CmapSelector(host.content_frame, colormaps=["viridis"], allow_custom=True) + assert list(selector.cmap_combobox["values"]) == ["Comfort", "viridis"] + assert selector.get_cmap().name == "Comfort" + + changes = [] + selector.on_change = changes.append + selector._on_scale_saved(GradientScale("Warm", [(0, "#ffffff"), (1, "#ff0000")])) + assert list(selector.cmap_combobox["values"]) == ["Warm", "Comfort", "viridis"] + assert selector.get_cmap().name == "Warm" and len(changes) == 1 + + +def test_cmap_selector_without_custom_has_no_button(host): + selector = CmapSelector(host.content_frame, colormaps=["viridis"]) + assert list(selector.cmap_combobox["values"]) == ["viridis"] and not hasattr(selector, "new_scale_button") diff --git a/Python_Engine/Python/tests/test_colour_scales.py b/Python_Engine/Python/tests/test_colour_scales.py new file mode 100644 index 0000000..843ec51 --- /dev/null +++ b/Python_Engine/Python/tests/test_colour_scales.py @@ -0,0 +1,184 @@ +import json + +import numpy as np +import pytest +from matplotlib.colors import to_hex + +from python_toolkit.plot.colour_scales import ( + ColourScale, + ColourScaleError, + ColourScaleLibrary, + DataSummary, + GradientScale, + PALETTES, + ThresholdScale, + palette_colours, + suggest_thresholds, +) + +COMFORT = dict(thresholds=[18, 21, 24], colours=["#0000ff", "#00ffff", "#00ff00", "#ff0000"], + labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC", group="TM59") + + +def colour_of(mapping, value): + return to_hex(mapping.cmap(mapping.norm(value))) + + +# -- thresholds hold in data units, whatever data is passed in ---------------- + +@pytest.mark.parametrize("data", [[19, 20, 22], np.linspace(-50, 200, 30), [23.9], None]) +def test_bands_fixed_for_any_data(data): + mapping = ThresholdScale("Comfort", **COMFORT).mapping(data) + assert colour_of(mapping, 17.99) == "#0000ff" + assert colour_of(mapping, 18.0) == "#00ffff" # boundary belongs to the band above + assert colour_of(mapping, 22.0) == "#00ff00" + assert colour_of(mapping, 24.0) == "#ff0000" + assert colour_of(mapping, -1000) == "#0000ff" and colour_of(mapping, 1000) == "#ff0000" + assert mapping.band_labels == ["Cold", "Cool", "Comfortable", "Hot"] + + +def test_auto_band_labels_and_band_of(): + scale = ThresholdScale("Plain", [10, 20], ["red", "green", "blue"]) + assert scale.band_labels() == ["< 10", "10 - 20", ">= 20"] + assert [scale.band_of(v) for v in (5, 10, 19.9, 20, 99)] == [0, 1, 1, 2, 2] + partly = ThresholdScale("Partly", [10, 20], ["red", "green", "blue"], labels=["Low", None, ""]) + assert partly.band_labels() == ["Low", "10 - 20", ">= 20"] + + +@pytest.mark.parametrize("kwargs,message", [ + (dict(thresholds=[], colours=["red"]), "at least one"), + (dict(thresholds=[2, 1], colours=["r", "g", "b"]), "increasing"), + (dict(thresholds=[1, 2], colours=["red", "green"]), "3 bands"), + (dict(thresholds=[1], colours=["red", "green"], labels=["a"]), "one label per band"), + (dict(thresholds=[1], colours=["red", "notacolour"]), "not a colour"), +]) +def test_threshold_validation(kwargs, message): + with pytest.raises(ColourScaleError, match=message): + ThresholdScale("Bad", **kwargs) + + +def test_gradient_relative_stretches_to_data_absolute_does_not(): + relative = GradientScale.from_palette("Rel", "Traffic light") + assert relative.mapping([10, 30]).norm.vmin == 10 and relative.mapping([10, 30]).norm.vmax == 30 + absolute = GradientScale("Abs", [(0, "blue"), (100, "red")], relative=False) + assert (absolute.mapping([10, 30]).norm.vmin, absolute.mapping([10, 30]).norm.vmax) == (0, 100) + stepped = GradientScale("Steps", [(0, "blue"), (1, "red")], bins=4).mapping([0, 8]) + assert len({colour_of(stepped, v) for v in np.linspace(0, 8, 50)}) == 4 + with pytest.raises(ColourScaleError): + GradientScale("Bad", [(0, "red"), (2, "blue")], relative=True) + + +def test_mapping_colours_for_handles_missing_values(): + rgba = ThresholdScale("C", **COMFORT).mapping().colours_for([17, None, "x", 30]) + assert np.isnan(rgba[1]).all() and np.isnan(rgba[2]).all() + assert to_hex(rgba[3]) == "#ff0000" + + +# -- data passed in ---------------------------------------------------------- + +def test_data_summary_ignores_unreadable_values(): + summary = DataSummary.from_data([1, 2, None, "n/a", float("nan"), 3, 10]) + assert summary.count == 4 and summary.minimum == 1 and summary.maximum == 10 + assert summary.histogram[0].sum() == 4 + with pytest.raises(ColourScaleError): + DataSummary.from_data([None, "x"]) + + +def test_suggest_thresholds_methods(): + data = np.concatenate([np.full(90, 20.0), np.linspace(20, 30, 10)]) + assert suggest_thresholds([0, 100], 4, "equal") == [25, 50, 75] + assert suggest_thresholds([0.3, 9.7], 5, "nice") == [2, 4, 6, 8] + with pytest.raises(ColourScaleError, match="repeated values"): + suggest_thresholds(data, 4, "quantile") + q = suggest_thresholds(np.arange(100), 4, "quantile") + assert len(q) == 3 and q[0] < q[1] < q[2] + + +@pytest.mark.parametrize("data,bands,expected", [ + ([16, 30], 5, [17.5, 20, 22.5, 25]), + ([8, 24], 4, [10, 15, 20]), + ([0, 95], 4, [25, 50, 75]), + ([1000, 250000], 5, [50000, 100000, 150000, 200000]), +]) +def test_nice_thresholds_fall_inside_the_data(data, bands, expected): + thresholds = suggest_thresholds(data, bands, "nice") + assert thresholds == pytest.approx(expected) + assert all(min(data) < t < max(data) for t in thresholds) + + +def test_threshold_scale_from_data(): + scale = ThresholdScale.from_data("Loads", np.linspace(0, 95, 50), bands=4, method="nice", + palette="Okabe-Ito (colour-blind safe)", group="Loads") + assert scale.thresholds == [25, 50, 75] and scale.bands == 4 and scale.group == "Loads" + assert len(palette_colours("Traffic light", 7)) == 7 + + +# -- persistence ------------------------------------------------------------- + +def test_round_trip_through_dict(): + for scale in (ThresholdScale("Comfort", **COMFORT), GradientScale.from_palette("G", "LTC Maya", bins=6)): + rebuilt = ColourScale.from_dict(json.loads(json.dumps(scale.to_dict()))) + assert type(rebuilt) is type(scale) and rebuilt.to_dict() == scale.to_dict() + + +def test_library_sets(tmp_path): + library = ColourScaleLibrary(tmp_path / "scales.json") + library.save(ThresholdScale("Comfort", **COMFORT)) + library.save(GradientScale.from_palette("Heat", "LTC Heatmap", group="Loads")) + library.save(ThresholdScale("Overheating", [26, 28], ["green", "orange", "red"], group="TM59")) + reopened = ColourScaleLibrary(tmp_path / "scales.json") + assert reopened.groups() == ["TM59", "Loads"] + assert reopened.names("TM59") == ["Comfort", "Overheating"] + assert reopened.get("Comfort").labels[-1] == "Hot" + with pytest.raises(ColourScaleError, match="already exists"): + reopened.save(ThresholdScale("Comfort", **COMFORT)) + reopened.rename_group("TM59", "Overheating checks") + reopened.delete_group("Loads") + final = ColourScaleLibrary(tmp_path / "scales.json") + assert final.groups() == ["Overheating checks"] and len(final) == 2 + + +def test_unreadable_entries_reported_and_kept(tmp_path): + path = tmp_path / "mixed.json" + path.write_text(json.dumps({"version": 2, "scales": [ + ThresholdScale("Good", [1], ["red", "blue"]).to_dict(), + {"type": "thresholds", "name": "Broken", "thresholds": [2, 1], "colours": ["a"]}, + ]}), encoding="utf-8") + library = ColourScaleLibrary(path) + assert library.names() == ["Good"] and "Broken" in library.problems[0] + library.save(ThresholdScale("New", [5], ["red", "blue"])) + names_on_disk = [e["name"] for e in json.loads(path.read_text(encoding="utf-8"))["scales"]] + assert "Broken" in names_on_disk # never silently deleted + + +def test_corrupt_library_raises(tmp_path): + path = tmp_path / "bad.json" + path.write_text("{not json", encoding="utf-8") + with pytest.raises(ColourScaleError, match="Cannot read"): + ColourScaleLibrary(path) + + +def test_palettes_are_valid(): + for name, colours in PALETTES.items(): + assert len(colours) >= 3, name + GradientScale.from_palette(name, name) + + +def test_palettes_registered_as_colour_maps(): + from matplotlib import colormaps + from python_toolkit.plot.colour_scales import PALETTE_CMAPS, palette_names + + for name in PALETTE_CMAPS.values(): + assert name in colormaps and f"{name}_r" in colormaps + names = palette_names() + assert names[:len(PALETTES)] == list(PALETTES) and "magma" in names and "okabe_ito" not in names + assert palette_colours("magma", 3)[0] == "#000004" + with pytest.raises(ColourScaleError, match="Unknown palette"): + palette_colours("no such map", 3) + + +def test_to_colormap_keeps_band_widths(): + scale = ThresholdScale("T", [10, 30], ["#0000ff", "#00ff00", "#ff0000"]) + cmap = scale.to_colormap(np.array([0, 40])) + colours = [to_hex(cmap(x)) for x in (0.1, 0.5, 0.9)] + assert colours == ["#0000ff", "#00ff00", "#ff0000"] and cmap.name == "T" From 2f1610401cc411c0be1698b78d2759b252d588b8 Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Wed, 28 Oct 2026 16:39:27 +0000 Subject: [PATCH 2/8] refactored to better combine cmaps and pallettes --- .../bhom_tkinter/widgets/cmap_selector.py | 122 +--- .../windows/colour_scale_builder.py | 413 +++++++----- .../src/python_toolkit/plot/colour_scales.py | 612 +++++------------- .../src/python_toolkit/plot/palettes.py | 66 ++ .../Python/tests/test_colour_scale_builder.py | 227 +++++-- .../Python/tests/test_colour_scales.py | 238 +++---- 6 files changed, 773 insertions(+), 905 deletions(-) create mode 100644 Python_Engine/Python/src/python_toolkit/plot/palettes.py diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index 9165a0f..446ac2d 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py @@ -9,8 +9,7 @@ from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget from python_toolkit.bhom_tkinter.widgets._packing_options import PackingOptions -from python_toolkit.bhom_tkinter.widgets.button import Button -from python_toolkit.plot.colour_scales import ColourScale, ColourScaleLibrary +from python_toolkit.plot import palettes from python_toolkit.bhom.analytics import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.theming.scaling import scale_pad @@ -29,48 +28,6 @@ class CmapSelector(BHoMBaseWidget): * `List[str]`: a list of colour strings (hex codes or named colours) that is auto-converted to a `ListedColormap`. """ - CATEGORICAL_CMAPS = [ - "Accent", - "Dark2", - "Paired", - "Pastel1", - "Pastel2", - "Set1", - "Set2", - "Set3", - "tab10", - "tab20", - "tab20b", - "tab20c", - ] - - CONTINUOUS_CMAPS = [ - "viridis", - "plasma", - "inferno", - "magma", - "cividis", - "turbo", - "Blues", - "Greens", - "Greys", - "Oranges", - "Purples", - "Reds", - "YlGn", - "YlGnBu", - "YlOrBr", - "YlOrRd", - "coolwarm", - "seismic", - "Spectral", - "RdYlBu", - "RdYlGn", - "twilight", - "twilight_shifted", - "hsv", - ] - def __init__( self, parent: ttk.Frame, @@ -80,7 +37,6 @@ def __init__( default_cmap: Optional[CmapInput] = None, plot_size: tuple[int, int] = (400, 50), dropdown_position: Literal["n", "e", "s", "w"] = "n", - allow_custom: bool = False, **kwargs ) -> None: """ @@ -93,7 +49,8 @@ def __init__( `List[str]` of colour strings. When provided the preset `cmap_set` selection is ignored. cmap_set: Preset colormap set used when `colormaps` is `None`. - Allowed values: "all", "continuous", "categorical". + Allowed values: "all", "continuous", "categorical", "colourblind" + (see `python_toolkit.plot.palettes`). cmap_bins: Number of discrete gradient bands in the preview swatch. default_cmap: Optional default colormap to pre-select. Accepts the same input types as items in `colormaps`. @@ -101,9 +58,6 @@ def __init__( dropdown_position: Position of the dropdown relative to the preview swatch. "n" = above, "s" = below, "w" = left, "e" = right. - allow_custom: When True, colour scales saved in the - `ColourScaleLibrary` are listed first, and a button opens the - `ColourScaleBuilder` to make a new one. **kwargs: Additional Frame options. """ super().__init__(parent, **kwargs) @@ -119,12 +73,7 @@ def __init__( self.cmap_frame.pack(side="top", fill="both", expand=True, anchor=self._pack_anchor) self.colormap_var = tk.StringVar(value="viridis") - self._all_colormaps = self._get_all_colormaps() - self._preset_map: Dict[str, List[str]] = { - "all": self._all_colormaps, - "continuous": self._filter_available(self.CONTINUOUS_CMAPS), - "categorical": self._filter_available(self.CATEGORICAL_CMAPS), - } + self._all_colormaps = palettes.names() self._uses_explicit_colormaps = colormaps is not None self.cmap_frame.columnconfigure(0, weight=1) @@ -172,73 +121,12 @@ def __init__( else: current_colormaps = self._preset_colormaps(self.cmap_set_var.get()) - if allow_custom: - current_colormaps = self._saved_scale_labels(current_colormaps) + current_colormaps - self._populate_cmap_list(current_colormaps) # Resolve default_cmap: may itself be a Colormap object or colour list self._default_label = self._resolve_default_label(default_cmap, current_colormaps) self._select_default_cmap(current_colormaps) - if allow_custom: - self.new_scale_button = Button(header, text="New colour scale...", command=self._open_scale_builder) - self.new_scale_button.pack(side=tk.TOP, anchor=self._pack_anchor, fill="x", pady=(4, 0)) - - def _saved_scale_labels(self, existing: List[str]) -> List[str]: - """Register every saved colour scale as a custom entry and return their labels.""" - labels: List[str] = [] - for scale in ColourScaleLibrary().scales(): - label = self._unique_label(scale.name, existing + labels) - self._custom_cmaps[label] = scale.to_colormap() - labels.append(label) - return labels - - def _open_scale_builder(self) -> None: - """Open the colour scale builder; a saved scale is added to the list and selected.""" - # imported here: the builder window is built from these widgets - from python_toolkit.bhom_tkinter.windows.colour_scale_builder import ColourScaleBuilder - - ColourScaleBuilder(self.winfo_toplevel(), on_save=self._on_scale_saved).run() - - def _on_scale_saved(self, scale: ColourScale) -> None: - existing = list(self.cmap_combobox["values"]) - label = self._unique_label(scale.name, existing) - self._custom_cmaps[label] = scale.to_colormap() - self._populate_cmap_list([label] + existing) - self.colormap_var.set(label) - self._update_cmap_sample() - self._fire_on_change(self.get()) - - def _get_all_colormaps(self) -> List[str]: - """Return all registered colormap names, including reversed variants. - - Returns: - List[str]: Sorted list of available colormap names. - """ - # Base names available in this matplotlib build - base_names = set(mpl.colormaps()) - - # Include reversed variants (name_r) next to each base map - all_names = set(base_names) - for name in list(base_names): - if not name.endswith("_r"): - all_names.add(f"{name}_r") - - return sorted(all_names) - - def _filter_available(self, names: List[str]) -> List[str]: - """Filter a candidate list to names available in the current matplotlib build. - - Args: - names: Candidate colormap names. - - Returns: - List[str]: Candidate names available in the current environment. - """ - available = set(self._all_colormaps) - return [name for name in names if name in available] - def _with_reversed(self, names: List[str]) -> List[str]: """Return colormap names with reversed variants next to base maps. @@ -269,7 +157,7 @@ def _preset_colormaps(self, cmap_set: str) -> List[str]: List[str]: Colormap names for the requested preset. """ key = (cmap_set or "all").lower() - return self._with_reversed(self._preset_map.get(key, self._preset_map["all"])) + return self._with_reversed(palettes.names(key if key in palettes.KINDS else None)) def _resolve_colormaps(self, colormaps: List[CmapInput]) -> tuple[List[str], Dict[str, Colormap]]: """Normalise a mixed list of colormap inputs into display labels and a custom-cmap registry. diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py index bf2e531..86dc896 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -1,8 +1,8 @@ """Window for building colour scales from the data they will colour. Pass the data in and the window shows its distribution, suggests band thresholds, and -lets the user colour, label and save the scale into a named set of the colour scale -library (``python_toolkit.plot.colour_scales``):: +lets the user colour, label and save the scale to the saved scales file +(``python_toolkit.plot.colour_scales``):: builder = ColourScaleBuilder(parent, data=room_temperatures, units="degC") builder.run() @@ -11,8 +11,10 @@ from __future__ import annotations +import math import tkinter as tk from tkinter import ttk +from pathlib import Path from typing import Callable, Iterable, List, Optional import numpy as np @@ -22,39 +24,48 @@ from python_toolkit.bhom_tkinter.bhom_base_child_window import BHoMBaseChildWindow from python_toolkit.bhom_tkinter.windows.warning_box import WarningBox from python_toolkit.bhom_tkinter.widgets._grid_options import GridOptions -from python_toolkit.bhom_tkinter.widgets.button import Button -from python_toolkit.bhom_tkinter.widgets.check_box_selection import CheckboxSelection from python_toolkit.bhom_tkinter.widgets.colour_picker import ColourPicker from python_toolkit.bhom_tkinter.widgets.drop_down_selection import DropDownSelection from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets.label import Label -from python_toolkit.bhom_tkinter.widgets.radio_selection import RadioSelection from python_toolkit.bhom_tkinter.widgets.spinbox import Spinbox from python_toolkit.bhom_tkinter.widgets.validated_entry_box import ValidatedEntryBox +from python_toolkit.bhom_tkinter.theming.scaling import scale as scale_px +from python_toolkit.plot import palettes from python_toolkit.plot.colour_scales import ( - DEFAULT_SET, - PALETTES, SUGGESTION_METHODS, ColourScale, ColourScaleError, - ColourScaleLibrary, - DataSummary, - GradientScale, - ThresholdScale, clean_data, - palette_colours, - palette_names, + load_scales, + save_scale, suggest_thresholds, ) -THRESHOLDS = "Threshold bands" -GRADIENT = "Gradient" MAX_BANDS = 12 +TYPING_DELAY = 700 # ms to wait after the last keystroke, so "22" is not read as "2" first +PLOT_WIDTH = 560 # the plot, the controls and the band table all share this width ERROR_COLOUR = "#c0392b" +def _spin_step(span: float) -> float: + """A round step (1, 2 or 5 x 10^n) of about a hundredth of the span, for spinning a threshold.""" + raw = span / 100 if span > 0 else 0.01 + power = 10 ** math.floor(math.log10(raw)) + return next(factor * power for factor in (5, 2, 1) if factor * power <= raw) + + +def _plain(box: ValidatedEntryBox) -> ValidatedEntryBox: + """Drop the tick and the message line an entry box reserves, so its edges line up with its neighbours. + + Problems are reported in the window's status line instead.""" + box.success_label.pack_forget() + box.error_label.pack_forget() + return box + + class ColourScaleBuilder(BHoMBaseChildWindow): - """Build, preview and save a ThresholdScale or GradientScale against real data.""" + """Build, preview and save a ColourScale against real data.""" def __init__( self, @@ -62,7 +73,7 @@ def __init__( data: Optional[Iterable] = None, units: Optional[str] = None, scale: Optional[ColourScale] = None, - library: Optional[ColourScaleLibrary] = None, + library_path: Optional[Path] = None, on_save: Optional[Callable[[ColourScale], None]] = None, palette: Optional[str] = None, **kwargs, @@ -73,19 +84,20 @@ def __init__( data: Values the scale will colour; drives the histogram and suggestions. units: Units of the data, stored with the scale. scale: An existing scale to edit (saving replaces it). - library: Library to save into (defaults to the user's library). + library_path: File to save into (defaults to the user's saved scales). on_save: Called with the saved scale. palette: Palette or matplotlib colour map to start from (e.g. the plot's current one). """ self.values = clean_data(data) - self.summary = DataSummary.from_data(self.values) if self.values.size else None self.units = units if units is not None else (scale.units if scale else None) - self.library = library if library is not None else ColourScaleLibrary() + self.library_path = library_path self.editing = scale self.on_save = on_save self.saved_scale: Optional[ColourScale] = None self._band_rows: List[dict] = [] self._pending = None + self._syncing = False + self._suggest_job = None self._start_palette = palette super().__init__( parent, @@ -97,108 +109,100 @@ def __init__( modal=parent is not None, defer_show=True, resizable=True, - min_width=kwargs.pop("min_width", 620), - min_height=kwargs.pop("min_height", 800), + min_width=kwargs.pop("min_width", 400), + min_height=kwargs.pop("min_height", 400), **kwargs, ) self._build_contents() self.build() self._load(scale) + self.update_idletasks() + self._apply_sizing() # the band rows were added after the window first sized itself # ── layout ───────────────────────────────────────────────────────────── def _build_contents(self) -> None: frame = self.content_frame - sets = self.library.groups() or [DEFAULT_SET] - default_set = self.editing.group if self.editing else sets[0] - - self.name = ValidatedEntryBox(frame, id="name", helper_text="Name", required=False, width=30, - on_change=lambda _v: self._schedule_preview(), # re-checks, clearing old errors - build_options=GridOptions(row=0, column=0, sticky="w", padx=6, pady=3)) - self.group = DropDownSelection(frame, id="group", helper_text="Set (type a new name to start a set)", - options=sets, default=default_set, state="normal", width=28, - build_options=GridOptions(row=0, column=1, sticky="w", padx=6, pady=3)) - self.kind = RadioSelection(frame, id="kind", fields=[THRESHOLDS, GRADIENT], default=THRESHOLDS, - orient="horizontal", command=lambda _v: self._on_kind_changed(), - build_options=GridOptions(row=1, column=0, columnspan=2, sticky="w", padx=6, pady=3)) - self.data_text = Label(frame, text=self._summary_text(), - build_options=GridOptions(row=2, column=0, columnspan=2, sticky="w", padx=6)) - self.preview = FigureContainer(frame, id="preview", rigid_width=560, rigid_height=130, - build_options=GridOptions(row=3, column=0, columnspan=2, sticky="w", padx=6, pady=4)) - - suggest = ttk.Frame(frame) - suggest.grid(row=5, column=0, columnspan=2, sticky="w", padx=6, pady=3) - self.band_count = Spinbox(suggest, id="bands", helper_text="Bands", values=list(range(2, MAX_BANDS + 1)), - default=5, width=5, build_options=GridOptions(row=0, column=0, sticky="w", padx=(0, 8))) - self.method = DropDownSelection(suggest, id="method", helper_text="Breaks", options=list(SUGGESTION_METHODS), - default="nice", state="readonly", width=10, + frame.columnconfigure(0, weight=1) + left = dict(column=0, sticky="ew", padx=0) + + self.name = _plain(ValidatedEntryBox( + frame, id="name", helper_text="Name", required=False, width=30, + on_change=lambda _v: self._schedule_preview(TYPING_DELAY), # re-checks, clearing old errors + build_options=GridOptions(row=0, pady=3, **left))) + self.data_text = Label(frame, text=self._summary_text(), build_options=GridOptions(row=2, **left)) + self.preview = FigureContainer(frame, id="preview", rigid_width=PLOT_WIDTH, rigid_height=130, + build_options=GridOptions(row=3, pady=4, **left)) + self.status = Label(frame, text="", foreground=ERROR_COLOUR, wraplength=scale_px(PLOT_WIDTH), justify="left", + build_options=GridOptions(row=4, **left)) + + controls = ttk.Frame(frame) + controls.grid(row=5, pady=3, **left) + controls.columnconfigure(2, weight=1) # the palette takes the spare width + self.band_count = Spinbox(controls, id="bands", helper_text="Bands", values=list(range(2, MAX_BANDS + 1)), + default=5, width=4, command=lambda _v: self._auto_suggest(TYPING_DELAY), + build_options=GridOptions(row=0, column=0, sticky="w", padx=(0, 8))) + self.method = DropDownSelection(controls, id="method", helper_text="Breaks", options=list(SUGGESTION_METHODS), + default="nice", state="readonly", width=7, + command=lambda _v: self._auto_suggest(0), build_options=GridOptions(row=0, column=1, sticky="w", padx=(0, 8))) - palettes = palette_names() - self.palette = DropDownSelection(suggest, id="palette", helper_text="Palette / colour map", options=palettes, - default=self._start_palette if self._start_palette in palettes else None, - state="readonly", width=28, command=lambda _v: self._recolour(), - build_options=GridOptions(row=0, column=2, sticky="w", padx=(0, 8))) - self.suggest_button = Button(suggest, text="Suggest from data", command=self._suggest, width=18, - build_options=GridOptions(row=0, column=3, sticky="sw")) - for widget in (self.band_count, self.method, self.palette, self.suggest_button): + options = palettes.names() + self.palette = DropDownSelection(controls, id="palette", helper_text="Palette / colour map", options=options, + default=self._start_palette if self._start_palette in options else "viridis", + state="readonly", width=6, command=lambda _v: self._recolour(), + build_options=GridOptions(row=0, column=2, sticky="ew")) + for widget in (self.band_count, self.method, self.palette): widget.build() - if self.summary is None: - self.suggest_button.button.configure(state="disabled") + if not self.values.size: # breaks are suggested from data; without it the thresholds are typed in + self.band_count.spinbox.configure(state="disabled") + self.method.combobox.configure(state="disabled") self.bands_frame = ttk.Frame(frame) - self.bands_frame.grid(row=6, column=0, columnspan=2, sticky="w", padx=6, pady=3) - self.gradient_frame = ttk.Frame(frame) - self.gradient_frame.grid(row=6, column=0, columnspan=2, sticky="w", padx=6, pady=3) - self.reverse = CheckboxSelection(self.gradient_frame, id="reverse", fields=["Reverse"], - command=lambda _v: self._schedule_preview(), - build_options=GridOptions(row=0, column=0, sticky="w", padx=(0, 12))) - self.steps = Spinbox(self.gradient_frame, id="steps", helper_text="Steps (0 = smooth)", - values=[0] + list(range(2, 21)), default=0, width=5, - command=lambda _v: self._schedule_preview(), - build_options=GridOptions(row=0, column=1, sticky="w")) - self.reverse.build() - self.steps.build() - - self.status = Label(frame, text="", foreground=ERROR_COLOUR, wraplength=560, justify="left", - build_options=GridOptions(row=4, column=0, columnspan=2, sticky="w", padx=6)) - self.widgets = [self.name, self.group, self.kind, self.data_text, self.preview, self.status] + self.bands_frame.grid(row=6, pady=3, **left) + self.bands_frame.columnconfigure(1, weight=1) # the label box takes the spare width + self.widgets = [self.name, self.data_text, self.preview, self.status] def _summary_text(self) -> str: - if self.summary is None: + if not self.values.size: return "No data passed in: set the thresholds by hand." - s = self.summary + q1, q2, q3 = np.quantile(self.values, [0.25, 0.5, 0.75]) units = f" {self.units}" if self.units else "" - return (f"{s.count} values from {s.minimum:.4g} to {s.maximum:.4g}{units}; " - f"median {s.quartiles[1]:.4g}, middle half {s.quartiles[0]:.4g} to {s.quartiles[2]:.4g}") + return (f"{self.values.size} values from {self.values.min():.4g} to {self.values.max():.4g}{units}; " + f"median {q2:.4g}, middle half {q1:.4g} to {q3:.4g}") # ── state ────────────────────────────────────────────────────────────── def _load(self, scale: Optional[ColourScale]) -> None: - if isinstance(scale, GradientScale): + if scale is not None: self.name.set(scale.name) - self.kind.set(GRADIENT) - self.steps.set(scale.bins or 0) - elif isinstance(scale, ThresholdScale): - self.name.set(scale.name) - self._set_bands(scale.thresholds, scale.colours, scale.labels) - elif self.summary is not None: + if isinstance(scale.cmap, str): + self.palette.set(scale.cmap) + self._set_bands(scale.thresholds, scale.colours(), scale.labels) + elif self.values.size: self.name.set(self._unused_name("New scale")) self._suggest() else: self.name.set(self._unused_name("New scale")) - self._set_bands([1.0, 2.0], palette_colours(self.palette.get(), 3), None) - self._on_kind_changed() - - def _on_kind_changed(self) -> None: - threshold = self.kind.get() == THRESHOLDS - if threshold: - self.gradient_frame.grid_remove() - self.bands_frame.grid() - else: - self.bands_frame.grid_remove() - self.gradient_frame.grid() + self._set_bands([1.0, 2.0], palettes.sample(self.palette.get(), 3), None) self._schedule_preview() + def _auto_suggest(self, delay: int) -> None: + """Re-suggest the bands once the band count or break method has settled.""" + if self._syncing or not self.values.size: + return + if self._suggest_job is not None: + self.after_cancel(self._suggest_job) + self._suggest_job = self.after(delay, self._run_auto_suggest) + + def _run_auto_suggest(self) -> None: + self._suggest_job = None + try: + bands = int(self.band_count.get()) + except ValueError: # half-typed count + return + if 2 <= bands <= MAX_BANDS: + self._suggest() + def _suggest(self) -> None: try: bands = int(self.band_count.get()) @@ -206,13 +210,75 @@ def _suggest(self) -> None: except (ColourScaleError, ValueError) as e: self.status.set(str(e)) return - self._set_bands(thresholds, palette_colours(self.palette.get(), len(thresholds) + 1), None) + n = len(thresholds) + 1 + palette = self.palette.get() + old_colours = [row["colour"].get() for row in self._band_rows] + old_labels = [(row["label"].get() or "").strip() or None for row in self._band_rows] + fresh = palettes.sample(palette, n) + # keep hand-picked colours and any labels on the bands that remain; new breaks only replace the thresholds + customised = bool(old_colours) and old_colours != palettes.sample(palette, len(old_colours)) + colours = [old_colours[i] if customised and i < len(old_colours) else fresh[i] for i in range(n)] + labels = (old_labels + [None] * n)[:n] + self._set_bands(thresholds, colours, labels if any(labels) else None) + + def _split_band(self, index: int) -> None: + """Add a band by splitting this one in two at the middle of its range; the new band starts empty.""" + try: + thresholds, colours, labels = self._read_bands() + except ColourScaleError as e: + self.status.set(str(e)) + return + n = len(colours) + if n >= MAX_BANDS: + return + typical = float(np.mean(np.diff(thresholds))) if len(thresholds) > 1 else 0.0 + if not typical and self.values.size: + typical = float(self.values.max() - self.values.min()) / n + typical = typical or 1.0 + lower = thresholds[index - 1] if index > 0 else None + upper = thresholds[index] if index < n - 1 else None + data_lo = float(self.values.min()) if self.values.size else None + data_hi = float(self.values.max()) if self.values.size else None + # an open end is split against the data's extreme, or one typical band width beyond the last threshold + lo = lower if lower is not None else (data_lo if data_lo is not None and data_lo < upper else upper - typical) + hi = upper if upper is not None else (data_hi if data_hi is not None and data_hi > lower else lower + typical) + new = float(f"{(lo + hi) / 2:.6g}") + if not lo < new < hi: + self.status.set("There is no room to split this band; move its thresholds apart first.") + return + was_customised = colours != palettes.sample(self.palette.get(), n) + thresholds.insert(index, new) + colours.insert(index + 1, colours[index]) + labels.insert(index + 1, None) + self._rebuild(thresholds, colours, labels, was_customised) + + def _remove_band(self, index: int) -> None: + """Remove a band; its range joins the band after it (before it, for the last band).""" + try: + thresholds, colours, labels = self._read_bands() + except ColourScaleError as e: + self.status.set(str(e)) + return + n = len(colours) + if n <= 2: + return + was_customised = colours != palettes.sample(self.palette.get(), n) + thresholds.pop(index if index < n - 1 else n - 2) + colours.pop(index) + labels.pop(index) + self._rebuild(thresholds, colours, labels, was_customised) + + def _rebuild(self, thresholds, colours, labels, was_customised: bool) -> None: + """Show an edited table: hand-picked colours stay, otherwise the palette is spread over the new bands.""" + if not was_customised: + colours = palettes.sample(self.palette.get(), len(colours)) + self._set_bands(thresholds, colours, labels if any(labels) else None) def _recolour(self) -> None: """A new palette recolours the bands, keeping their thresholds and labels.""" if not self._band_rows: return - for row, colour in zip(self._band_rows, palette_colours(self.palette.get(), len(self._band_rows))): + for row, colour in zip(self._band_rows, palettes.sample(self.palette.get(), len(self._band_rows))): row["colour"].set(colour) self._schedule_preview() @@ -221,58 +287,77 @@ def _set_bands(self, thresholds, colours, labels) -> None: child.destroy() self._band_rows = [] n = len(colours) - headers = ("Colour", "Label (legend)", "From", "Up to") + # thresholds are spin boxes: step about 1% of the data range, anywhere from one range below to one above + lo = min([*thresholds, *([self.values.min()] if self.values.size else [])]) + hi = max([*thresholds, *([self.values.max()] if self.values.size else [])]) + span = (hi - lo) or 1.0 + step = _spin_step(span) + headers = ("Colour", "Label (legend)", "From", "Up to", "") for col, text in enumerate(headers): - ttk.Label(self.bands_frame, text=text, style="Caption.TLabel").grid(row=0, column=col, sticky="w", padx=4) + ttk.Label(self.bands_frame, text=text, style="Caption.TLabel").grid(row=0, column=col, sticky="w", padx=(0, 8)) for i in range(n): picker = ColourPicker(self.bands_frame, default_colour=colours[i], swatch_width=36, swatch_height=20, command=lambda _c: self._schedule_preview()) - picker.grid(row=i + 1, column=0, sticky="nw", padx=4, pady=(6, 0)) - label = ValidatedEntryBox(self.bands_frame, required=False, width=22, - on_change=lambda _v: self._schedule_preview()) - label.grid(row=i + 1, column=1, sticky="w", padx=4) + picker.grid(row=i + 1, column=0, sticky="w", padx=(0, 8)) + label = _plain(ValidatedEntryBox(self.bands_frame, required=False, width=10, + on_change=lambda _v: self._schedule_preview(TYPING_DELAY))) + label.grid(row=i + 1, column=1, sticky="ew", padx=(0, 8)) label.set((labels[i] or "") if labels else "") lower = ttk.Label(self.bands_frame, text="") - lower.grid(row=i + 1, column=2, sticky="nw", padx=4, pady=(6, 0)) + lower.grid(row=i + 1, column=2, sticky="w", padx=(0, 8)) upper = None if i < n - 1: - upper = ValidatedEntryBox(self.bands_frame, required=False, width=10, - on_change=lambda _v: self._schedule_preview()) - upper.grid(row=i + 1, column=3, sticky="w", padx=4) + upper = Spinbox(self.bands_frame, from_=lo - span, to=hi + span, increment=step, width=10, + command=lambda _v: self._schedule_preview(TYPING_DELAY)) + upper.spinbox.configure(format="%.6g") # no float noise while spinning + upper.grid(row=i + 1, column=3, sticky="w") upper.set(f"{thresholds[i]:.6g}") else: - ttk.Label(self.bands_frame, text="and above").grid(row=i + 1, column=3, sticky="nw", padx=4, pady=(6, 0)) - self._band_rows.append({"colour": picker, "label": label, "lower": lower, "upper": upper}) + ttk.Label(self.bands_frame, text="and above").grid(row=i + 1, column=3, sticky="w") + actions = ttk.Frame(self.bands_frame) + actions.grid(row=i + 1, column=4, sticky="e", padx=(8, 0)) + split = ttk.Button(actions, text="Split", width=6, command=lambda i=i: self._split_band(i)) + remove = ttk.Button(actions, text="Remove", width=7, command=lambda i=i: self._remove_band(i)) + split.pack(side="left", padx=(0, 4)) + remove.pack(side="left") + if n >= MAX_BANDS: + split.state(["disabled"]) + if n <= 2: + remove.state(["disabled"]) + self._band_rows.append({"colour": picker, "label": label, "lower": lower, "upper": upper, + "split": split, "remove": remove}) + self._syncing = True # showing the count must not re-suggest the bands self.band_count.set(n) + self._syncing = False self._schedule_preview() + if self._has_been_shown: # the window follows the number of band rows + self.update_idletasks() + self._apply_sizing() - def current_scale(self) -> ColourScale: - """The scale described by the window right now (raises ColourScaleError if invalid).""" - name = (self.name.get() or "").strip() - group = (self.group.get() or "").strip() or DEFAULT_SET - if self.kind.get() == GRADIENT: - name = self.palette.get() - colours = PALETTES.get(name) or palette_colours(name, 9) - if self.reverse.get(): - colours = colours[::-1] - n = len(colours) - steps = int(self.steps.get() or 0) - return GradientScale(name, [(i / (n - 1), c) for i, c in enumerate(colours)], relative=True, - bins=steps or None, units=self.units, group=group) + def _read_bands(self): + """The table as (thresholds, colours, labels); raises ColourScaleError for a threshold that is not a number.""" thresholds = [] for i, row in enumerate(self._band_rows[:-1]): - text = (row["upper"].get() or "").strip() + text = str(row["upper"].get()).strip() try: thresholds.append(float(text)) except ValueError: raise ColourScaleError(f"Band {i + 1}: '{text}' is not a number.") from None colours = [row["colour"].get() for row in self._band_rows] labels = [(row["label"].get() or "").strip() or None for row in self._band_rows] - return ThresholdScale(name, thresholds, colours, labels=labels if any(labels) else None, - units=self.units, group=group) + return thresholds, colours, labels + + def current_scale(self) -> ColourScale: + """The scale described by the window right now (raises ColourScaleError if invalid).""" + name = (self.name.get() or "").strip() + palette = self.palette.get() + thresholds, colours, labels = self._read_bands() + # keep the palette as the scale's colours unless a band colour was changed by hand + cmap = palette if colours == palettes.sample(palette, len(colours)) else colours + return ColourScale(name, thresholds, cmap, labels if any(labels) else None, self.units) def _unused_name(self, base: str) -> str: - names = set(self.library.names()) + names = {s.name for s in load_scales(self.library_path)} n = 1 name = base while name in names: @@ -284,7 +369,7 @@ def _save(self) -> None: """Validate, save to the library and close; errors are shown in a pop-up and stay in the window.""" try: scale = self.current_scale() - self.library.save(scale, overwrite=self.editing is not None and self.editing.name == scale.name) + save_scale(scale, self.library_path, overwrite=self.editing is not None and self.editing.name == scale.name) except (ColourScaleError, OSError) as e: message = str(e) if "already exists" in message: @@ -294,7 +379,7 @@ def _save(self) -> None: box.build() box.run() return - CONSOLE_LOGGER.info(f"Saved colour scale '{scale.name}' in set '{scale.group}'.") + CONSOLE_LOGGER.info(f"Saved colour scale '{scale.name}'.") self.saved_scale = scale if self.on_save is not None: self.on_save(scale) @@ -302,13 +387,13 @@ def _save(self) -> None: # ── preview ──────────────────────────────────────────────────────────── - def _schedule_preview(self) -> None: + def _schedule_preview(self, delay: int = 250) -> None: if self._pending is not None: try: self.after_cancel(self._pending) except tk.TclError: pass - self._pending = self.after(250, self._update_preview) + self._pending = self.after(delay, self._update_preview) def _update_preview(self) -> None: self._pending = None @@ -318,41 +403,55 @@ def _update_preview(self) -> None: self.status.set(str(e)) return self.status.set("") - if isinstance(scale, ThresholdScale): - for row, (lower, _upper) in zip(self._band_rows, scale.band_ranges()): - row["lower"].configure(text="below" if lower is None else f"{lower:.6g}") - self.preview.embed_figure(preview_figure(scale, self.values, self.summary)) - - -def preview_figure(scale: ColourScale, values: np.ndarray, summary: Optional[DataSummary]) -> Figure: - """Histogram of the data over the scale's colours (or the colours alone without data).""" - fig = Figure(figsize=(5.6, 1.3), dpi=100) - ax = fig.add_axes([0.04, 0.2, 0.94, 0.76]) - sample = values if values.size else scale.preview_data() - mapping = scale.mapping(sample) - lo, hi = (summary.minimum, summary.maximum) if summary else (float(sample.min()), float(sample.max())) - if lo == hi: - lo, hi = lo - 0.5, hi + 0.5 - pad = (hi - lo) * 0.04 - xs = np.linspace(lo - pad, hi + pad, 400) - colours = mapping.cmap(mapping.norm(xs)) - ax.imshow(colours[np.newaxis, :, :], aspect="auto", extent=(xs[0], xs[-1], 0, 1), alpha=0.85, + for row, lower in zip(self._band_rows, [None] + scale.thresholds): + row["lower"].configure(text="below" if lower is None else f"{lower:.6g}") + style = ttk.Style() + self.preview.embed_figure(preview_figure(scale, self.values, + background=style.lookup("TFrame", "background") or "#ffffff", + foreground=style.lookup("TLabel", "foreground") or "#000000")) + + +def preview_figure(scale: ColourScale, values: np.ndarray, background: str = "#ffffff", + foreground: str = "#000000") -> Figure: + """Histogram of the data over the scale's colours (or the colours alone without data). + + `background` and `foreground` are the window's colours, so the plot sits in light or dark mode. + """ + fig = Figure(figsize=(5.6, 1.3), dpi=100, facecolor=background) + ax = fig.add_axes([0.0, 0.2, 1.0, 0.76], facecolor=background) + cmap, norm = scale.mapping() + lo, hi = scale.value_range(values) + xs = np.linspace(lo, hi, 400) + ax.imshow(cmap(norm(xs))[np.newaxis, :, :], aspect="auto", extent=(xs[0], xs[-1], 0, 1), alpha=0.85, origin="lower", zorder=0) - if summary is not None: - counts, edges = summary.histogram - heights = counts / max(counts.max(), 1) - ax.bar(edges[:-1], heights, width=np.diff(edges), align="edge", color="#202020", alpha=0.55, - edgecolor="#ffffff", linewidth=0.6, zorder=1) - if isinstance(scale, ThresholdScale): - for t in scale.thresholds: - if xs[0] <= t <= xs[-1]: - ax.axvline(t, color="#000000", linewidth=1.2, zorder=2) + if values.size: + counts, edges = np.histogram(values, bins=30, range=(lo, hi)) + ax.bar(edges[:-1], counts / max(counts.max(), 1), width=np.diff(edges), align="edge", color=foreground, + alpha=0.45, edgecolor=background, linewidth=0.6, zorder=1) + for t in scale.thresholds: + if xs[0] <= t <= xs[-1]: + ax.axvline(t, color=foreground, linewidth=1.2, zorder=2) ax.set_xlim(xs[0], xs[-1]) ax.set_ylim(0, 1.05) ax.set_yticks([]) - ax.tick_params(labelsize=7) + ax.tick_params(labelsize=7, colors=foreground) for side in ("top", "right", "left"): ax.spines[side].set_visible(False) + ax.spines["bottom"].set_color(foreground) return fig +if __name__ == "__main__": + import tempfile + + # Build a colour scale from sample data; saved to a temp file so your own saved scales are untouched. + temperatures = np.random.default_rng(1).normal(22, 3, 300) + builder = ColourScaleBuilder( + data=temperatures, + units="degC", + palette="okabe_ito", + library_path=Path(tempfile.gettempdir()) / "colour_scale_builder_demo.json", + on_save=lambda scale: print(f"Saved: {scale!r}"), + ) + builder.run() + print(builder.saved_scale) diff --git a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py index a034516..7d5d035 100644 --- a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py +++ b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py @@ -1,112 +1,124 @@ -"""Colour scales defined in data units, with user-defined sets saved for reuse. +"""Colour scales: data broken into bands at thresholds in data units, coloured by a palette. A matplotlib Colormap only knows positions from 0 to 1, so a saved "18 / 21 / 24 degC" band -set drifts whenever the data range changes. A ColourScale keeps its definition in data -units and produces the matching (Colormap, Normalize) pair for whatever data is passed in: +set drifts whenever the data range changes. A ColourScale keeps its thresholds in data units +and produces the matching (Colormap, Normalize) pair, whatever data it is used on: - scale = ThresholdScale("Comfort", thresholds=[18, 21, 24], - colours=["#3b4cc0", "#8db0fe", "#f4987a", "#b40426"], - labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") - mapping = scale.mapping(room_temperatures) # pass the data in - ax.scatter(x, y, c=room_temperatures, cmap=mapping.cmap, norm=mapping.norm) + scale = ColourScale("Comfort", thresholds=[18, 21, 24], cmap="coolwarm", + labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") + cmap, norm = scale.mapping() + ax.scatter(x, y, c=room_temperatures, cmap=cmap, norm=norm) + scale.cmap = "okabe_ito" # the colours can change; the thresholds stay -Scales can be suggested from the data (equal interval, quantile, or rounded "nice" breaks), -and are saved in a ColourScaleLibrary under named sets (e.g. "TM59", "Part L"). +`cmap` is a palette name (see `python_toolkit.plot.palettes`) or an explicit list of colours, +one per band. """ from __future__ import annotations import json import math -from abc import ABC, abstractmethod -from dataclasses import dataclass, field from pathlib import Path -from typing import Any, ClassVar, Dict, Iterable, List, Optional, Sequence, Tuple, Type +from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union import numpy as np from matplotlib import colormaps -from matplotlib.colors import ( - BoundaryNorm, - Colormap, - LinearSegmentedColormap, - ListedColormap, - Normalize, - to_hex, - to_rgba, -) +from matplotlib.colors import BoundaryNorm, Colormap, ListedColormap, to_hex, to_rgba from python_toolkit.bhom.logging import CONSOLE_LOGGER +from python_toolkit.plot import palettes LIBRARY_FILE = Path.home() / ".bhom" / "colour_scales.json" -LIBRARY_VERSION = 1 -DEFAULT_SET = "My scales" - -# Preset palettes for building scales (colour-blind safe sets first). -PALETTES: Dict[str, List[str]] = { - "Okabe-Ito (colour-blind safe)": ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"], - "Viridis (colour-blind safe)": ["#440154", "#3b528b", "#21918c", "#5ec962", "#fde725"], - "Cividis (colour-blind safe)": ["#00204c", "#31446b", "#666870", "#988e5d", "#ffe945"], - "Cool to warm": ["#3b4cc0", "#8db0fe", "#dddddd", "#f4987a", "#b40426"], - "Traffic light": ["#1a9850", "#fee08b", "#d73027"], - "LTC Heatmap": ["#000004", "#51127c", "#b63679", "#fb8861", "#fcffa4"], - "LTC Maya": ["#5c8286", "#a1b18c", "#e7cca6", "#d98f79", "#b35b5a"], - "LTC Paloma": ["#1a2a40", "#456a73", "#82a69d", "#d9ccb6", "#bf8865"], -} - -# Palettes registered as matplotlib colour maps (with _r), so every colour map list offers them. -# Viridis and Cividis are already matplotlib maps. -PALETTE_CMAPS: Dict[str, str] = { - "Okabe-Ito (colour-blind safe)": "okabe_ito", - "Cool to warm": "cool_to_warm", - "Traffic light": "traffic_light", - "LTC Heatmap": "ltc_heatmap", - "LTC Maya": "ltc_maya", - "LTC Paloma": "ltc_paloma", -} - -SUGGESTION_METHODS = ("equal", "quantile", "nice") +SUGGESTION_METHODS = ("equal", "quantile", "nice", "log") class ColourScaleError(ValueError): """A colour scale definition, or the saved library, is invalid.""" -# --------------------------------------------------------------------------- -# Data passed in -# --------------------------------------------------------------------------- +class ColourScale: + """A named set of bands split at `thresholds` (data units), coloured by `cmap`.""" -def clean_data(data: Optional[Iterable]) -> np.ndarray: - """Finite float values from any iterable; None, NaN and non-numbers are dropped.""" - if data is None: - return np.empty(0) - numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) - return numbers[np.isfinite(numbers)] + def __init__(self, name: str, thresholds: Sequence[float], cmap: Union[str, Sequence[str]] = "viridis", + labels: Optional[Sequence[Optional[str]]] = None, units: Optional[str] = None): + self.name = (name or "").strip() + if not self.name: + raise ColourScaleError("A colour scale needs a name.") + self.thresholds = [float(t) for t in thresholds] + if not self.thresholds: + raise ColourScaleError("A colour scale needs at least one threshold.") + if any(b <= a for a, b in zip(self.thresholds, self.thresholds[1:])): + raise ColourScaleError("Thresholds must be strictly increasing.") + if labels is not None and len(labels) != self.bands: + raise ColourScaleError(f"Give one label per band ({self.bands}), or none.") + self.labels = [str(l) if l else None for l in labels] if labels is not None else None + self.units = units + self.cmap = cmap + @property + def bands(self) -> int: + return len(self.thresholds) + 1 -@dataclass(frozen=True) -class DataSummary: - """What a scale needs to know about the data: range, spread and distribution.""" + @property + def cmap(self) -> Union[str, List[str]]: + return self._cmap + + @cmap.setter + def cmap(self, value: Union[str, Sequence[str]]) -> None: + if isinstance(value, str): + if value not in colormaps: + raise ColourScaleError(f"Unknown colour map '{value}'.") + self._cmap = value + return + colours = [_hex(c) for c in value] + if len(colours) != self.bands: + raise ColourScaleError(f"{len(self.thresholds)} threshold(s) make {self.bands} bands, " + f"but {len(colours)} colour(s) were given.") + self._cmap = colours - count: int - minimum: float - maximum: float - mean: float - quartiles: Tuple[float, float, float] - histogram: Tuple[np.ndarray, np.ndarray] # (counts, bin edges) + def colours(self) -> List[str]: + """One hex colour per band.""" + return list(self._cmap) if not isinstance(self._cmap, str) else palettes.sample(self._cmap, self.bands) - @classmethod - def from_data(cls, data: Iterable, bins: int = 30) -> "DataSummary": + def value_range(self, data: Optional[Iterable] = None) -> Tuple[float, float]: + """The data range, or a span around the thresholds without data.""" values = clean_data(data) - if values.size == 0: - raise ColourScaleError("No numeric values in the data passed in.") - lo, hi = float(values.min()), float(values.max()) - if lo == hi: - lo, hi = lo - 0.5, hi + 0.5 - counts, edges = np.histogram(values, bins=bins, range=(lo, hi)) - q1, q2, q3 = (float(q) for q in np.quantile(values, [0.25, 0.5, 0.75])) - return cls(int(values.size), float(values.min()), float(values.max()), float(values.mean()), - (q1, q2, q3), (counts, edges)) + if values.size: + lo, hi = float(values.min()), float(values.max()) + else: + pad = (self.thresholds[-1] - self.thresholds[0]) / max(self.bands - 2, 1) or 1.0 + lo, hi = self.thresholds[0] - pad, self.thresholds[-1] + pad + return (lo - 0.5, hi + 0.5) if lo == hi else (lo, hi) + + def mapping(self) -> Tuple[Colormap, BoundaryNorm]: + """The colormap and normaliser to colour any data with; values beyond the ends take the end colours.""" + edges = [self.thresholds[0] - 1] + self.thresholds + [self.thresholds[-1] + 1] + return ListedColormap(self.colours(), name=self.name), BoundaryNorm(edges, self.bands, clip=True) + + def band_labels(self) -> List[str]: + """Labels as given, else ranges such as '< 18', '18 - 21', '>= 24'.""" + t = self.thresholds + auto = [f"< {_fmt(t[0])}"] + [f"{_fmt(a)} - {_fmt(b)}" for a, b in zip(t, t[1:])] + [f">= {_fmt(t[-1])}"] + given = self.labels or [None] * len(auto) + return [g or a for g, a in zip(given, auto)] + + def to_dict(self) -> Dict[str, Any]: + return {"name": self.name, "thresholds": self.thresholds, "cmap": self._cmap, + "labels": self.labels, "units": self.units} + @classmethod + def from_dict(cls, data: Dict[str, Any]) -> "ColourScale": + # "colours" is the older name for the colour list + return cls(data["name"], data["thresholds"], data.get("cmap") or data["colours"], + data.get("labels"), data.get("units")) + + def __repr__(self) -> str: + return f"ColourScale({self.name!r}, thresholds={self.thresholds}, cmap={self._cmap!r})" + + +# --------------------------------------------------------------------------- +# Suggesting thresholds from data +# --------------------------------------------------------------------------- def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List[float]: """Inner boundaries splitting the data into `bands` bands. @@ -114,6 +126,8 @@ def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List equal: equal-width bands across the data range quantile: roughly the same number of values in each band nice: equal-width bands on rounded 1 / 2 / 5 x 10^n steps + log: bands of equal ratio (each break a fixed multiple of the last), rounded to 3 significant + figures; needs every value above zero """ if bands < 2: raise ColourScaleError("A threshold scale needs at least 2 bands.") @@ -134,24 +148,28 @@ def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List if len(unique) < bands - 1: raise ColourScaleError("Too many repeated values for that many quantile bands; use fewer bands.") return unique - + if method == "log": + if lo <= 0: + raise ColourScaleError("Logarithmic breaks need every value above zero; use another break method.") + cuts = [float(f"{v:.3g}") for v in np.geomspace(lo, hi, bands + 1)[1:-1]] + if any(b <= a for a, b in zip(cuts, cuts[1:])) or cuts[0] <= lo or cuts[-1] >= hi: + raise ColourScaleError("The data range is too narrow for that many logarithmic bands; use fewer bands.") + return cuts return _nice_thresholds(lo, hi, bands - 1) def _nice_thresholds(lo: float, hi: float, wanted: int) -> List[float]: """Rounded breaks (multiples of 1, 2, 2.5 or 5 x 10^n) strictly inside the data range. - Picks the step whose breaks come closest to `wanted`, then keeps the middle `wanted` + Picks the step with the fewest breaks that is still at least `wanted`, then keeps the middle `wanted` of them, so every band contains data rather than extending beyond it.""" - raw = (hi - lo) / (wanted + 1) - exponent = math.floor(math.log10(raw)) + exponent = math.floor(math.log10((hi - lo) / (wanted + 1))) best = None for power in (exponent - 1, exponent, exponent + 1): for factor in (1, 2, 2.5, 5): step = factor * 10 ** power - first, last = math.floor(lo / step) + 1, math.ceil(hi / step) - 1 - inner = [round(k * step, 10) for k in range(first, last + 1)] - if not inner: + inner = [round(k * step, 10) for k in range(math.floor(lo / step) + 1, math.ceil(hi / step))] + if len(inner) < wanted: # always return the number of breaks asked for continue score = abs(len(inner) - wanted) + (0.5 if factor == 2.5 else 0.0) # prefer rounder steps if best is None or score < best[0]: @@ -159,395 +177,62 @@ def _nice_thresholds(lo: float, hi: float, wanted: int) -> List[float]: if best is None: # range too narrow for rounded breaks return [float(v) for v in np.linspace(lo, hi, wanted + 2)[1:-1]] inner = best[1] - if len(inner) > wanted: - start = (len(inner) - wanted) // 2 - inner = inner[start:start + wanted] - return inner - - -def register_palette_cmaps() -> None: - """Add the preset palettes to matplotlib's colour maps (idempotent).""" - for palette, name in PALETTE_CMAPS.items(): - if name not in colormaps: - cmap = LinearSegmentedColormap.from_list(name, PALETTES[palette]) - colormaps.register(cmap, name=name) - colormaps.register(cmap.reversed(), name=f"{name}_r") - - -def palette_names() -> List[str]: - """Preset palettes first, then every matplotlib colour map (no reversed copies).""" - preset = set(PALETTE_CMAPS.values()) - return list(PALETTES) + sorted((n for n in colormaps if not n.endswith("_r") and n not in preset), key=str.lower) - - -def palette_colours(palette: str, count: int) -> List[str]: - """`count` colours sampled evenly from a preset palette or a matplotlib colour map.""" - if palette in PALETTES: - cmap = LinearSegmentedColormap.from_list(palette, PALETTES[palette]) - elif palette in colormaps: - cmap = colormaps[palette] - else: - raise ColourScaleError(f"Unknown palette or colour map '{palette}'.") - if count == 1: - return [to_hex(cmap(0.5))] - return [to_hex(cmap(i / (count - 1))) for i in range(count)] - - -# --------------------------------------------------------------------------- -# Scales -# --------------------------------------------------------------------------- - -@dataclass -class ScaleMapping: - """Everything a plot needs to colour values with a scale.""" - - cmap: Colormap - norm: Normalize - ticks: List[float] - tick_labels: List[str] - band_labels: Optional[List[str]] = None # threshold scales: one per band, for legends - - def colours_for(self, values: Iterable) -> np.ndarray: - """RGBA per value (NaN for values that cannot be read).""" - data = np.array([_to_float(v) for v in values], dtype=float) - out = np.full((data.size, 4), np.nan) - ok = np.isfinite(data) - if ok.any(): - out[ok] = self.cmap(self.norm(data[ok])) - return out - - -class ColourScale(ABC): - """Base class: a named colour scale defined in data units. - - Subclasses produce a ScaleMapping from the data passed in, and round-trip through - plain dicts so they can be saved. `group` is the user-defined set the scale belongs to. - """ - - kind: ClassVar[str] = "" - _registry: ClassVar[Dict[str, Type["ColourScale"]]] = {} - - def __init__(self, name: str, units: Optional[str] = None, description: str = "", - group: str = DEFAULT_SET): - self.name = validate_name(name) - self.units = units - self.description = description - self.group = group or DEFAULT_SET - - def __init_subclass__(cls, **kwargs): - super().__init_subclass__(**kwargs) - if cls.kind: - ColourScale._registry[cls.kind] = cls - - @abstractmethod - def mapping(self, data: Optional[Iterable] = None) -> ScaleMapping: - """Colormap and normaliser for this scale, fitted to `data` where the scale is relative.""" - - @abstractmethod - def _definition(self) -> Dict[str, Any]: - """Subclass-specific fields for to_dict.""" - - def to_dict(self) -> Dict[str, Any]: - return {"type": self.kind, "name": self.name, "units": self.units, - "description": self.description, "group": self.group, **self._definition()} - - @classmethod - def from_dict(cls, data: Dict[str, Any]) -> "ColourScale": - kind = data.get("type") - scale_cls = ColourScale._registry.get(kind) - if scale_cls is None: - raise ColourScaleError(f"Unknown colour scale type '{kind}'.") - return scale_cls._from_definition(data) - - @classmethod - @abstractmethod - def _from_definition(cls, data: Dict[str, Any]) -> "ColourScale": - """Build from a dict written by to_dict.""" - - def preview_data(self) -> np.ndarray: - """Representative values spanning the scale, for swatches without real data.""" - return np.linspace(0.0, 1.0, 11) - - def to_colormap(self, data: Optional[Iterable] = None, samples: int = 256) -> Colormap: - """A plain 0-1 colormap that looks like this scale across its range (band widths kept), - for widgets that only take a Colormap. Plots should use `mapping`, which keeps data units.""" - mapping = self.mapping(data if data is not None else self.preview_data()) - values = np.linspace(mapping.norm.vmin, mapping.norm.vmax, samples) - return ListedColormap(mapping.cmap(mapping.norm(values)), name=self.name) - - def __repr__(self) -> str: - return f"{type(self).__name__}({self.name!r}, set={self.group!r})" - - -class GradientScale(ColourScale): - """A continuous gradient through colour stops. - - Stop positions are either absolute data values, or relative (0 = data minimum, - 1 = data maximum) so the gradient stretches to whatever data is passed in. - """ - - kind = "gradient" - - def __init__(self, name: str, stops: Sequence[Tuple[float, str]], relative: bool = True, - bins: Optional[int] = None, **kwargs): - super().__init__(name, **kwargs) - if len(stops) < 2: - raise ColourScaleError("A gradient needs at least 2 colour stops.") - self.stops = sorted(((float(p), _hex(c)) for p, c in stops), key=lambda s: s[0]) - self.relative = bool(relative) - self.bins = bins # None for smooth, or a number of discrete steps - positions = [p for p, _ in self.stops] - if positions[0] == positions[-1]: - raise ColourScaleError("Gradient stops must span a range.") - if self.relative and (positions[0] < 0 or positions[-1] > 1): - raise ColourScaleError("Relative stop positions must lie between 0 and 1.") - - @classmethod - def from_palette(cls, name: str, palette: str, **kwargs) -> "GradientScale": - if palette not in PALETTES: - raise ColourScaleError(f"Unknown palette '{palette}'.") - colours = PALETTES[palette] - n = len(colours) - return cls(name, [(i / (n - 1), c) for i, c in enumerate(colours)], relative=True, **kwargs) - - def value_range(self, data: Optional[Iterable] = None) -> Tuple[float, float]: - if not self.relative: - return self.stops[0][0], self.stops[-1][0] - values = clean_data(data) - if values.size == 0: - return 0.0, 1.0 - lo, hi = float(values.min()), float(values.max()) - return (lo - 0.5, hi + 0.5) if lo == hi else (lo, hi) - - def mapping(self, data: Optional[Iterable] = None) -> ScaleMapping: - vmin, vmax = self.value_range(data) - first, last = self.stops[0][0], self.stops[-1][0] - nodes = [((p - first) / (last - first), c) for p, c in self.stops] - cmap = LinearSegmentedColormap.from_list(self.name, nodes) - if self.bins: - cmap = cmap.resampled(int(self.bins)) - edges = list(np.linspace(vmin, vmax, int(self.bins) + 1)) - norm = BoundaryNorm(edges, ncolors=int(self.bins), clip=True) - ticks = edges - else: - norm = Normalize(vmin=vmin, vmax=vmax, clip=True) - ticks = list(np.linspace(vmin, vmax, 6)) - return ScaleMapping(cmap, norm, ticks, [_fmt(t) for t in ticks]) - - def _definition(self) -> Dict[str, Any]: - return {"stops": [[p, c] for p, c in self.stops], "relative": self.relative, "bins": self.bins} - - @classmethod - def _from_definition(cls, data: Dict[str, Any]) -> "GradientScale": - return cls(data["name"], [tuple(s) for s in data["stops"]], relative=data.get("relative", True), - bins=data.get("bins"), units=data.get("units"), description=data.get("description", ""), - group=data.get("group") or DEFAULT_SET) - - -class ThresholdScale(ColourScale): - """Bands with fixed boundaries in data units: one colour (and optional label) per band. - - `thresholds` are the inner boundaries; values below the first threshold take the first - colour and values at or above the last take the last, so the bands hold for any data. - """ - - kind = "thresholds" - - def __init__(self, name: str, thresholds: Sequence[float], colours: Sequence[str], - labels: Optional[Sequence[Optional[str]]] = None, **kwargs): - super().__init__(name, **kwargs) - self.thresholds = [float(t) for t in thresholds] - self.colours = [_hex(c) for c in colours] - if not self.thresholds: - raise ColourScaleError("A threshold scale needs at least one threshold.") - if any(b <= a for a, b in zip(self.thresholds, self.thresholds[1:])): - raise ColourScaleError("Thresholds must be strictly increasing.") - if len(self.colours) != len(self.thresholds) + 1: - raise ColourScaleError( - f"{len(self.thresholds)} threshold(s) make {len(self.thresholds) + 1} bands, " - f"but {len(self.colours)} colour(s) were given.") - if labels is not None and len(labels) != len(self.colours): - raise ColourScaleError(f"Give one label per band ({len(self.colours)}), or none.") - self.labels = [None if not l else str(l) for l in labels] if labels is not None else None - - @classmethod - def from_data(cls, name: str, data: Iterable, bands: int = 5, method: str = "nice", - palette: str = "Viridis (colour-blind safe)", **kwargs) -> "ThresholdScale": - """Suggest thresholds from the data passed in, coloured from a preset palette.""" - thresholds = suggest_thresholds(data, bands, method) - return cls(name, thresholds, palette_colours(palette, len(thresholds) + 1), **kwargs) - - @property - def bands(self) -> int: - return len(self.colours) - - def band_ranges(self) -> List[Tuple[Optional[float], Optional[float]]]: - """(lower, upper) per band; None for the open ends.""" - edges: List[Optional[float]] = [None] + list(self.thresholds) + [None] - return list(zip(edges[:-1], edges[1:])) - - def band_labels(self) -> List[str]: - """Labels as given, else ranges such as '< 18', '18 - 21', '>= 24'.""" - auto = [] - for lower, upper in self.band_ranges(): - if lower is None: - auto.append(f"< {_fmt(upper)}") - elif upper is None: - auto.append(f">= {_fmt(lower)}") - else: - auto.append(f"{_fmt(lower)} - {_fmt(upper)}") - if self.labels is None: - return auto - return [given or default for given, default in zip(self.labels, auto)] - - def band_of(self, value: float) -> int: - """Index of the band a value falls in.""" - return int(np.searchsorted(self.thresholds, float(value), side="right")) - - def mapping(self, data: Optional[Iterable] = None) -> ScaleMapping: - values = clean_data(data) - span = self.thresholds[-1] - self.thresholds[0] or 1.0 - lo = min(self.thresholds[0] - span / max(self.bands - 2, 1), float(values.min()) if values.size else math.inf) - hi = max(self.thresholds[-1] + span / max(self.bands - 2, 1), float(values.max()) if values.size else -math.inf) - edges = [lo] + self.thresholds + [hi + 1e-9] - cmap = ListedColormap(self.colours, name=self.name) - norm = BoundaryNorm(edges, ncolors=self.bands, clip=True) - return ScaleMapping(cmap, norm, list(self.thresholds), [_fmt(t) for t in self.thresholds], - band_labels=self.band_labels()) - - def preview_data(self) -> np.ndarray: - span = self.thresholds[-1] - self.thresholds[0] or 1.0 - pad = span / max(self.bands - 2, 1) - return np.linspace(self.thresholds[0] - pad, self.thresholds[-1] + pad, 101) - - def _definition(self) -> Dict[str, Any]: - return {"thresholds": self.thresholds, "colours": self.colours, "labels": self.labels} - - @classmethod - def _from_definition(cls, data: Dict[str, Any]) -> "ThresholdScale": - return cls(data["name"], data["thresholds"], data["colours"], labels=data.get("labels"), - units=data.get("units"), description=data.get("description", ""), - group=data.get("group") or DEFAULT_SET) + start = max(len(inner) - wanted, 0) // 2 + return inner[start:start + wanted] # --------------------------------------------------------------------------- -# Library: saved scales grouped in user-defined sets +# Saved scales: one JSON file, one entry per name # --------------------------------------------------------------------------- -class ColourScaleLibrary: - """Saved colour scales, grouped into named sets, stored as JSON. - - Entries that cannot be read are kept on disk, reported in `problems` and logged, - never silently dropped. - """ - - def __init__(self, path: Optional[Path] = None): - self.path = Path(path) if path is not None else LIBRARY_FILE - self.problems: List[str] = [] - self._scales: Dict[str, ColourScale] = {} - self._unreadable: List[Dict[str, Any]] = [] - self.reload() - - def reload(self) -> None: - self._scales.clear() - self._unreadable.clear() - self.problems = [] - if not self.path.exists(): - return +def load_scales(path: Optional[Path] = None) -> List[ColourScale]: + """Saved scales; entries that cannot be read are logged and skipped (never deleted from the file).""" + scales = [] + for entry in _read(path): try: - raw = json.loads(self.path.read_text(encoding="utf-8")) - except (OSError, ValueError) as e: - raise ColourScaleError(f"Cannot read the colour scale library {self.path}: {e}") from e - - entries = raw.get("scales", []) if isinstance(raw, dict) else raw - if not isinstance(entries, list): - raise ColourScaleError(f"{self.path} is not a colour scale library.") - for entry in entries: - try: - scale = ColourScale.from_dict(entry) - except (KeyError, TypeError, ValueError) as e: - name = entry.get("name", "?") if isinstance(entry, dict) else "?" - self.problems.append(f"Could not read saved scale '{name}': {e}") - self._unreadable.append(entry) - continue - self._scales[scale.name] = scale - for problem in self.problems: - CONSOLE_LOGGER.warning(problem) - - # -- queries ------------------------------------------------------------ - - def names(self, group: Optional[str] = None) -> List[str]: - return [s.name for s in self._scales.values() if group is None or s.group == group] - - def groups(self) -> List[str]: - """The user-defined sets, in first-seen order.""" - return list(dict.fromkeys(s.group for s in self._scales.values())) - - def scales(self, group: Optional[str] = None) -> List[ColourScale]: - return [s for s in self._scales.values() if group is None or s.group == group] - - def get(self, name: str) -> ColourScale: - if name not in self._scales: - raise KeyError(f"No saved colour scale named '{name}'.") - return self._scales[name] - - def __contains__(self, name: str) -> bool: - return name in self._scales - - def __len__(self) -> int: - return len(self._scales) - - # -- changes ------------------------------------------------------------ - - def save(self, scale: ColourScale, overwrite: bool = False) -> None: - if scale.name in self._scales and not overwrite: - raise ColourScaleError(f"A scale named '{scale.name}' already exists.") - self._scales[scale.name] = scale - self._write() - - def delete(self, name: str) -> None: - if name not in self._scales: - raise KeyError(f"No saved colour scale named '{name}'.") - del self._scales[name] - self._write() - - def rename_group(self, old: str, new: str) -> None: - for scale in self.scales(old): - scale.group = new - self._write() - - def delete_group(self, group: str) -> None: - for name in self.names(group): - del self._scales[name] - self._write() - - def clear(self) -> None: - self._scales.clear() - self._write() - - def _write(self) -> None: - self.path.parent.mkdir(parents=True, exist_ok=True) - payload = {"version": LIBRARY_VERSION, - "scales": [s.to_dict() for s in self._scales.values()] + self._unreadable} - tmp = self.path.with_suffix(".tmp") - tmp.write_text(json.dumps(payload, indent=2), encoding="utf-8") - tmp.replace(self.path) + scales.append(ColourScale.from_dict(entry)) + except (KeyError, TypeError, ValueError) as e: + CONSOLE_LOGGER.warning(f"Could not read saved scale '{entry.get('name', '?')}': {e}") + return scales + + +def save_scale(scale: ColourScale, path: Optional[Path] = None, overwrite: bool = False) -> None: + """Add a scale to the saved file; an existing name is only replaced with `overwrite`.""" + path = Path(path or LIBRARY_FILE) + entries = _read(path) + others = [e for e in entries if e.get("name") != scale.name] + if len(others) < len(entries) and not overwrite: + raise ColourScaleError(f"A scale named '{scale.name}' already exists.") + path.parent.mkdir(parents=True, exist_ok=True) + tmp = path.with_suffix(".tmp") + tmp.write_text(json.dumps({"version": 1, "scales": others + [scale.to_dict()]}, indent=2), encoding="utf-8") + tmp.replace(path) + + +def _read(path: Optional[Path]) -> List[Dict[str, Any]]: + path = Path(path or LIBRARY_FILE) + if not path.exists(): + return [] + try: + raw = json.loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError) as e: + raise ColourScaleError(f"Cannot read the colour scale library {path}: {e}") from e + entries = raw.get("scales") if isinstance(raw, dict) else raw + if not isinstance(entries, list) or not all(isinstance(e, dict) for e in entries): + raise ColourScaleError(f"{path} is not a colour scale library.") + return entries # --------------------------------------------------------------------------- # Helpers # --------------------------------------------------------------------------- -_INVALID_NAME_CHARS = set(r'\/:*?"<>|') - - -def validate_name(name: str) -> str: - name = (name or "").strip() - if not name: - raise ColourScaleError("A colour scale needs a name.") - if any(c in _INVALID_NAME_CHARS for c in name): - raise ColourScaleError("Names cannot contain \\ / : * ? \" < > |") - return name +def clean_data(data: Optional[Iterable]) -> np.ndarray: + """Finite float values from any iterable; None, NaN and non-numbers are dropped.""" + if data is None: + return np.empty(0) + numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) + return numbers[np.isfinite(numbers)] def _hex(colour: str) -> str: @@ -566,6 +251,3 @@ def _to_float(value) -> float: def _fmt(value: float) -> str: return f"{value:.4g}" - - -register_palette_cmaps() diff --git a/Python_Engine/Python/src/python_toolkit/plot/palettes.py b/Python_Engine/Python/src/python_toolkit/plot/palettes.py new file mode 100644 index 0000000..160b02b --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/plot/palettes.py @@ -0,0 +1,66 @@ +"""Colour palettes: matplotlib's colour maps plus the toolkit's own, always registered. + +Importing this module adds the toolkit palettes (and their reversed `_r` copies) to +matplotlib, so any palette name works anywhere a colour map name is accepted: + + palettes.names("colourblind") # ['viridis', 'cividis', ..., 'okabe_ito'] + palettes.sample("okabe_ito", 4) # four hex colours +""" + +from typing import List, Optional + +import numpy as np +from matplotlib import colormaps +from matplotlib.colors import LinearSegmentedColormap, ListedColormap, to_hex + +# The toolkit's own palettes: name -> (kind, colour-blind safe, colours). +CUSTOM = { + "okabe_ito": ("categorical", True, ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"]), + "cool_to_warm": ("continuous", False, ["#3b4cc0", "#8db0fe", "#dddddd", "#f4987a", "#b40426"]), + "traffic_light": ("continuous", False, ["#1a9850", "#fee08b", "#d73027"]), + "ltc_heatmap": ("continuous", False, ["#000004", "#51127c", "#b63679", "#fb8861", "#fcffa4"]), + "ltc_maya": ("continuous", False, ["#5c8286", "#a1b18c", "#e7cca6", "#d98f79", "#b35b5a"]), + "ltc_paloma": ("continuous", False, ["#1a2a40", "#456a73", "#82a69d", "#d9ccb6", "#bf8865"]), +} + +# matplotlib colour maps by kind; the toolkit palettes are added below. +KINDS = { + "categorical": ["Accent", "Dark2", "Paired", "Pastel1", "Pastel2", "Set1", "Set2", "Set3", + "tab10", "tab20", "tab20b", "tab20c"], + "continuous": ["viridis", "plasma", "inferno", "magma", "cividis", "turbo", "Blues", "Greens", "Greys", + "Oranges", "Purples", "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd", "coolwarm", "seismic", + "Spectral", "RdYlBu", "RdYlGn", "twilight", "twilight_shifted", "hsv"], + # perceptually uniform maps; matplotlib's own, so safe for the common colour vision deficiencies + "colourblind": ["viridis", "cividis", "plasma", "inferno", "magma"], +} + +for _name, (_kind, _safe, _colours) in CUSTOM.items(): + if _name not in colormaps: + _cmap = (ListedColormap(_colours, name=_name) if _kind == "categorical" + else LinearSegmentedColormap.from_list(_name, _colours)) + colormaps.register(_cmap, name=_name) + colormaps.register(_cmap.reversed(), name=f"{_name}_r") + KINDS[_kind].append(_name) + if _safe: + KINDS["colourblind"].append(_name) + + +def names(kind: Optional[str] = None) -> List[str]: + """Colour map names of a kind ("categorical", "continuous", "colourblind"), without reversed copies. + + With no kind, every registered colour map including the reversed `_r` copies. + """ + if kind is None: + return sorted(colormaps, key=str.lower) + return [name for name in KINDS[kind] if name in colormaps] + + +def sample(name: str, count: int) -> List[str]: + """`count` hex colours from a palette: the first ones for a categorical palette, else evenly spread.""" + cmap = colormaps[name] + base = name[:-2] if name.endswith("_r") else name + if base in KINDS["categorical"] and count <= cmap.N: + points = (np.arange(count) + 0.5) / cmap.N + else: + points = np.linspace(0, 1, count) if count > 1 else [0.5] + return [to_hex(cmap(p)) for p in points] diff --git a/Python_Engine/Python/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py index 5a80508..40dcbb7 100644 --- a/Python_Engine/Python/tests/test_colour_scale_builder.py +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -1,11 +1,13 @@ import numpy as np import pytest +from matplotlib.colors import to_hex from python_toolkit.bhom_tkinter.bhom_base_window import BHoMBaseWindow from python_toolkit.bhom_tkinter.widgets.cmap_selector import CmapSelector from python_toolkit.bhom_tkinter.windows import ColourScaleBuilder -from python_toolkit.bhom_tkinter.windows.colour_scale_builder import GRADIENT, preview_figure -from python_toolkit.plot.colour_scales import ColourScaleLibrary, DataSummary, GradientScale, ThresholdScale +from python_toolkit.bhom_tkinter.windows.colour_scale_builder import preview_figure +from python_toolkit.plot import palettes +from python_toolkit.plot.colour_scales import ColourScale, load_scales, save_scale @pytest.fixture(scope="module") @@ -40,43 +42,40 @@ def run(self): @pytest.fixture def library(tmp_path): - return ColourScaleLibrary(tmp_path / "scales.json") + return tmp_path / "scales.json" def test_builder_suggests_bands_from_data(host, library): - builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), units="degC", library=library) + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), units="degC", library_path=library) scale = builder.current_scale() - assert isinstance(scale, ThresholdScale) assert scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) - assert scale.units == "degC" + assert scale.units == "degC" and scale.cmap == "viridis" assert "200 values from 16 to 30 degC" in builder.data_text.get() -def test_builder_saves_labels_into_a_set(host, library): +def test_builder_saves_labels(host, library): saved = [] - builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library=library, on_save=saved.append) + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library_path=library, on_save=saved.append) builder.name.set("Comfort") - builder.group.value_var.set("Overheating") # typed into the editable set box builder._band_rows[0]["label"].set("Cold") builder._save() - reopened = ColourScaleLibrary(library.path) - scale = reopened.get("Comfort") + scale = load_scales(library)[0] assert saved and saved[0].name == "Comfort" - assert scale.group == "Overheating" and scale.band_labels()[0] == "Cold" + assert scale.name == "Comfort" and scale.band_labels()[0] == "Cold" def test_builder_reports_bad_thresholds_without_saving(host, library, warnings_shown): - builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library=library) + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library_path=library) builder._band_rows[0]["upper"].set("warm") builder._save() assert builder.saved_scale is None and "not a number" in builder.status.get() assert warnings_shown and "not a number" in warnings_shown[0][0] # shown in a pop-up, not only in the window - assert len(library) == 0 + assert load_scales(library) == [] def test_builder_name_clash_is_explained_and_default_names_are_free(host, library, warnings_shown): - library.save(ThresholdScale("New scale", [1, 2], ["#000000", "#808080", "#ffffff"])) - builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library=library) + save_scale(ColourScale("New scale", [1, 2], "viridis"), library) + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library_path=library) assert builder.name.get() == "New scale 2" builder.name.set("New scale") builder._save() @@ -86,51 +85,181 @@ def test_builder_name_clash_is_explained_and_default_names_are_free(host, librar assert builder.status.get() == "" # the old error does not linger -def test_builder_gradient_and_edit(host, library): - builder = ColourScaleBuilder(host, data=[0, 1, 2], library=library) - builder.kind.set(GRADIENT) - builder._on_kind_changed() - assert isinstance(builder.current_scale(), GradientScale) - existing = ThresholdScale("Existing", [1, 2], ["#000000", "#808080", "#ffffff"], labels=["a", "b", "c"]) - editor = ColourScaleBuilder(host, scale=existing, library=library) +def test_builder_log_breaks_and_edit(host, library): + builder = ColourScaleBuilder(host, data=np.geomspace(1, 1000, 100), library_path=library) + builder.method.set("log") + builder.band_count.set(3) + builder._suggest() + assert builder.current_scale().thresholds == pytest.approx([10, 100]) + existing = ColourScale("Existing", [1, 2], ["#000000", "#808080", "#ffffff"], labels=["a", "b", "c"]) + editor = ColourScaleBuilder(host, scale=existing, library_path=library) assert editor.current_scale().band_labels() == ["a", "b", "c"] + assert editor.current_scale().cmap == ["#000000", "#808080", "#ffffff"] def test_preview_with_and_without_data(): - scale = ThresholdScale("T", [20, 25], ["#0000ff", "#00ff00", "#ff0000"]) - values = np.linspace(16, 30, 50) - assert preview_figure(scale, values, DataSummary.from_data(values)).axes - assert preview_figure(scale, np.array([]), None).axes + scale = ColourScale("T", [20, 25], ["#0000ff", "#00ff00", "#ff0000"]) + assert preview_figure(scale, np.linspace(16, 30, 50)).axes + assert preview_figure(scale, np.array([])).axes -def test_builder_starts_from_a_colour_map_and_recolours(host, library): - from python_toolkit.plot.colour_scales import palette_colours - - builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 50), library=library, palette="magma") +def test_builder_starts_from_a_palette_and_recolours(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 50), library_path=library, palette="magma") assert builder.palette.get() == "magma" - assert [r["colour"].get() for r in builder._band_rows] == palette_colours("magma", 5) - builder.palette.set("Traffic light") + assert [r["colour"].get() for r in builder._band_rows] == palettes.sample("magma", 5) + assert builder.current_scale().cmap == "magma" # untouched band colours stay a palette reference + builder.palette.set("traffic_light") builder._recolour() scale = builder.current_scale() - assert scale.colours == palette_colours("Traffic light", 5) and scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + assert scale.cmap == "traffic_light" and scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + builder._band_rows[0]["colour"].set("#123456") + assert builder.current_scale().cmap[0] == "#123456" # a hand-picked colour makes it an explicit list -def test_cmap_selector_lists_saved_scales_and_adds_new_ones(host, tmp_path, monkeypatch): - from python_toolkit.plot import colour_scales +def test_cmap_selector_lists_palette_sets(host): + for cmap_set, expected in (("categorical", "okabe_ito"), ("colourblind", "okabe_ito"), ("continuous", "ltc_maya")): + values = list(CmapSelector(host.content_frame, cmap_set=cmap_set).cmap_combobox["values"]) + assert expected in values and f"{expected}_r" in values + assert "okabe_ito" not in CmapSelector(host.content_frame, cmap_set="continuous").cmap_combobox["values"] - monkeypatch.setattr(colour_scales, "LIBRARY_FILE", tmp_path / "scales.json") - ColourScaleLibrary().save(ThresholdScale("Comfort", [18, 24], ["#0000ff", "#00ff00", "#ff0000"])) - selector = CmapSelector(host.content_frame, colormaps=["viridis"], allow_custom=True) - assert list(selector.cmap_combobox["values"]) == ["Comfort", "viridis"] - assert selector.get_cmap().name == "Comfort" - changes = [] - selector.on_change = changes.append - selector._on_scale_saved(GradientScale("Warm", [(0, "#ffffff"), (1, "#ff0000")])) - assert list(selector.cmap_combobox["values"]) == ["Warm", "Comfort", "viridis"] - assert selector.get_cmap().name == "Warm" and len(changes) == 1 +def test_cmap_selector_lists_what_it_is_given(host): + selector = CmapSelector(host.content_frame, colormaps=["viridis"]) + assert list(selector.cmap_combobox["values"]) == ["viridis"] -def test_cmap_selector_without_custom_has_no_button(host): - selector = CmapSelector(host.content_frame, colormaps=["viridis"]) - assert list(selector.cmap_combobox["values"]) == ["viridis"] and not hasattr(selector, "new_scale_button") +def test_end_to_end_palette_to_saved_scale_to_colours(host, library): + """Pick a colour-blind palette in the selector, build a scale from data, save it, reload it and colour with it.""" + data = np.linspace(16, 30, 100) + selector = CmapSelector(host.content_frame, cmap_set="colourblind", default_cmap="okabe_ito") + assert selector.get() == "okabe_ito" + + builder = ColourScaleBuilder(host, data=data, library_path=library, palette=selector.get()) + builder.name.set("Comfort") + builder._save() + + scale = load_scales(library)[0] + assert scale.cmap == "okabe_ito" and scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + cmap, norm = scale.mapping() + colours = {to_hex(cmap(norm(v))) for v in data} + assert colours == set(palettes.sample("okabe_ito", 5)) # every band is used, in the palette's colours + + scale.cmap = "viridis" # swap the colours; the breaks hold + assert scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) and scale.colours() == palettes.sample("viridis", 5) + + +def test_bands_and_breaks_update_the_scale_without_a_button(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + assert len(builder._band_rows) == 5 + builder.band_count.set(3) # what the spinbox does when changed + builder._run_auto_suggest() # what fires once typing has paused + assert len(builder._band_rows) == 3 and builder.current_scale().thresholds == pytest.approx([20, 25]) + builder.method.set("equal") + builder.method.combobox.event_generate("<>") + builder._run_auto_suggest() + assert builder.current_scale().thresholds == pytest.approx([20.6667, 25.3333], abs=1e-3) + assert len(builder._band_rows) == 3 and builder.band_count.get() == 3 # showing the count does not loop + + +def test_typing_in_bands_waits_for_the_pause(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + builder.band_count.set("1") # first keystroke of "12": nothing happens yet + assert len(builder._band_rows) == 5 and builder._suggest_job is not None + builder.band_count.set("12") + builder._run_auto_suggest() + assert len(builder._band_rows) == 12 + builder.band_count.set("99") # out of range: ignored, bands stay as they are + builder._run_auto_suggest() + assert len(builder._band_rows) == 12 + + +def test_bands_and_breaks_are_locked_without_data(host, library): + builder = ColourScaleBuilder(host, library_path=library) + assert str(builder.band_count.spinbox.cget("state")) == "disabled" + assert str(builder.method.combobox.cget("state")) == "disabled" + + +def test_changing_the_bands_keeps_what_was_filled_in(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + for i, name in enumerate(["Cold", "Cool", "Comfy", "Warm"]): + builder._band_rows[i]["label"].set(name) + builder._band_rows[1]["colour"].set("#123456") + builder.band_count.set(4) + builder._run_auto_suggest() + scale = builder.current_scale() + assert scale.bands == 4 and scale.labels == ["Cold", "Cool", "Comfy", "Warm"] + assert scale.colours()[1] == "#123456" # the hand-picked colour stays + builder.band_count.set(6) # new bands start empty and take palette colours + builder._run_auto_suggest() + scale = builder.current_scale() + assert scale.labels[:4] == ["Cold", "Cool", "Comfy", "Warm"] and scale.labels[4:] == [None, None] + assert scale.colours()[1] == "#123456" and scale.colours()[5] == palettes.sample("viridis", 6)[5] + + +def test_changing_the_bands_recolours_untouched_colours(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + builder.band_count.set(3) + builder._run_auto_suggest() + assert builder.current_scale().cmap == "viridis" # still a palette reference, resampled for 3 bands + + +def test_thresholds_spin_in_round_steps(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + spin = builder._band_rows[0]["upper"].spinbox + assert float(spin.cget("increment")) == 0.1 # about 1% of the 14-wide range, rounded + for _ in range(5): + spin.event_generate("<>") + assert builder.current_scale().thresholds[0] == pytest.approx(17.5 + 0.5) + + +def test_split_a_band_adds_one_between_its_ends(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) # breaks 17.5 20 22.5 25 + builder._band_rows[1]["label"].set("Cool") + builder._split_band(1) # the band 17.5 to 20 becomes 17.5 to 18.75 and 18.75 to 20 + scale = builder.current_scale() + assert scale.thresholds == pytest.approx([17.5, 18.75, 20, 22.5, 25]) and scale.bands == 6 + assert scale.labels == [None, "Cool", None, None, None, None] # the label stays with the lower half + assert builder.band_count.get() == 6 + assert scale.cmap == "viridis" # still a palette, spread over six bands + + +def test_split_the_open_ends_against_the_data(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + builder._split_band(0) # below 17.5: split against the data minimum, 16 + assert builder.current_scale().thresholds[:2] == pytest.approx([16.75, 17.5]) + builder._split_band(len(builder._band_rows) - 1) # 25 and above: split against the data maximum, 30 + assert builder.current_scale().thresholds[-1] == pytest.approx(27.5) + + +def test_remove_a_band_merges_its_range_into_the_next(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + for i, name in enumerate(["a", "b", "c", "d", "e"]): + builder._band_rows[i]["label"].set(name) + builder._band_rows[2]["colour"].set("#123456") # a hand-picked colour, which makes colours explicit + builder._remove_band(1) + scale = builder.current_scale() + assert scale.thresholds == pytest.approx([17.5, 22.5, 25]) and scale.labels == ["a", "c", "d", "e"] # "c" now starts at 17.5 + assert scale.colours()[1] == "#123456" + builder._remove_band(len(builder._band_rows) - 1) # the last band: the one before it becomes open-ended + assert builder.current_scale().thresholds == pytest.approx([17.5, 22.5]) and builder.current_scale().labels == ["a", "c", "d"] + + +def test_bands_cannot_go_below_two_or_above_the_maximum(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + builder.band_count.set(2) + builder._run_auto_suggest() + assert "disabled" in builder._band_rows[0]["remove"].state() + builder._remove_band(0) + assert len(builder._band_rows) == 2 + builder.band_count.set(12) + builder._run_auto_suggest() + assert "disabled" in builder._band_rows[0]["split"].state() + builder._split_band(0) + assert len(builder._band_rows) == 12 + + +def test_split_refuses_a_bad_threshold_without_changing_the_table(host, library): + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) + builder._band_rows[0]["upper"].set("warm") + builder._split_band(1) + assert len(builder._band_rows) == 5 and "not a number" in builder.status.get() diff --git a/Python_Engine/Python/tests/test_colour_scales.py b/Python_Engine/Python/tests/test_colour_scales.py index 843ec51..247b8d2 100644 --- a/Python_Engine/Python/tests/test_colour_scales.py +++ b/Python_Engine/Python/tests/test_colour_scales.py @@ -2,88 +2,96 @@ import numpy as np import pytest +from matplotlib import colormaps from matplotlib.colors import to_hex +from python_toolkit.plot import palettes from python_toolkit.plot.colour_scales import ( ColourScale, ColourScaleError, - ColourScaleLibrary, - DataSummary, - GradientScale, - PALETTES, - ThresholdScale, - palette_colours, + load_scales, + save_scale, suggest_thresholds, ) -COMFORT = dict(thresholds=[18, 21, 24], colours=["#0000ff", "#00ffff", "#00ff00", "#ff0000"], - labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC", group="TM59") +COMFORT = dict(thresholds=[18, 21, 24], cmap=["#0000ff", "#00ffff", "#00ff00", "#ff0000"], + labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") -def colour_of(mapping, value): - return to_hex(mapping.cmap(mapping.norm(value))) +def colour_of(scale, value): + cmap, norm = scale.mapping() + return to_hex(cmap(norm(value))) -# -- thresholds hold in data units, whatever data is passed in ---------------- +# -- palettes ------------------------------------------------------------------ -@pytest.mark.parametrize("data", [[19, 20, 22], np.linspace(-50, 200, 30), [23.9], None]) -def test_bands_fixed_for_any_data(data): - mapping = ThresholdScale("Comfort", **COMFORT).mapping(data) - assert colour_of(mapping, 17.99) == "#0000ff" - assert colour_of(mapping, 18.0) == "#00ffff" # boundary belongs to the band above - assert colour_of(mapping, 22.0) == "#00ff00" - assert colour_of(mapping, 24.0) == "#ff0000" - assert colour_of(mapping, -1000) == "#0000ff" and colour_of(mapping, 1000) == "#ff0000" - assert mapping.band_labels == ["Cold", "Cool", "Comfortable", "Hot"] +def test_toolkit_palettes_are_always_registered(): + for name, (kind, _safe, _colours) in palettes.CUSTOM.items(): + assert name in colormaps and f"{name}_r" in colormaps + assert name in palettes.names(kind) + assert isinstance(colormaps["okabe_ito"], type(colormaps["Set1"])) # discrete, like the other categorical maps + assert "okabe_ito" in palettes.names("colourblind") and "ltc_maya" not in palettes.names("colourblind") + assert "viridis_r" in palettes.names() and "viridis_r" not in palettes.names("continuous") -def test_auto_band_labels_and_band_of(): - scale = ThresholdScale("Plain", [10, 20], ["red", "green", "blue"]) - assert scale.band_labels() == ["< 10", "10 - 20", ">= 20"] - assert [scale.band_of(v) for v in (5, 10, 19.9, 20, 99)] == [0, 1, 1, 2, 2] - partly = ThresholdScale("Partly", [10, 20], ["red", "green", "blue"], labels=["Low", None, ""]) - assert partly.band_labels() == ["Low", "10 - 20", ">= 20"] +def test_sample_takes_the_first_colours_of_a_categorical_palette(): + assert palettes.sample("okabe_ito", 3) == ["#e69f00", "#56b4e9", "#009e73"] + assert palettes.sample("magma", 3)[0] == "#000004" + assert len(palettes.sample("traffic_light", 7)) == 7 and len(palettes.sample("viridis", 1)) == 1 -@pytest.mark.parametrize("kwargs,message", [ - (dict(thresholds=[], colours=["red"]), "at least one"), - (dict(thresholds=[2, 1], colours=["r", "g", "b"]), "increasing"), - (dict(thresholds=[1, 2], colours=["red", "green"]), "3 bands"), - (dict(thresholds=[1], colours=["red", "green"], labels=["a"]), "one label per band"), - (dict(thresholds=[1], colours=["red", "notacolour"]), "not a colour"), -]) -def test_threshold_validation(kwargs, message): - with pytest.raises(ColourScaleError, match=message): - ThresholdScale("Bad", **kwargs) +# -- thresholds hold in data units, whatever data is passed in ---------------- +def test_bands_hold_in_data_units(): + scale = ColourScale("Comfort", **COMFORT) + assert colour_of(scale, 17.99) == "#0000ff" + assert colour_of(scale, 18.0) == "#00ffff" # boundary belongs to the band above + assert colour_of(scale, 22.0) == "#00ff00" + assert colour_of(scale, 24.0) == "#ff0000" + assert colour_of(scale, -1000) == "#0000ff" and colour_of(scale, 1000) == "#ff0000" -def test_gradient_relative_stretches_to_data_absolute_does_not(): - relative = GradientScale.from_palette("Rel", "Traffic light") - assert relative.mapping([10, 30]).norm.vmin == 10 and relative.mapping([10, 30]).norm.vmax == 30 - absolute = GradientScale("Abs", [(0, "blue"), (100, "red")], relative=False) - assert (absolute.mapping([10, 30]).norm.vmin, absolute.mapping([10, 30]).norm.vmax) == (0, 100) - stepped = GradientScale("Steps", [(0, "blue"), (1, "red")], bins=4).mapping([0, 8]) - assert len({colour_of(stepped, v) for v in np.linspace(0, 8, 50)}) == 4 - with pytest.raises(ColourScaleError): - GradientScale("Bad", [(0, "red"), (2, "blue")], relative=True) +def test_band_labels(): + assert ColourScale("Comfort", **COMFORT).band_labels() == ["Cold", "Cool", "Comfortable", "Hot"] + plain = ColourScale("Plain", [10, 20], "viridis") + assert plain.band_labels() == ["< 10", "10 - 20", ">= 20"] + assert ColourScale("Partly", [10, 20], "viridis", labels=["Low", None, ""]).band_labels() == ["Low", "10 - 20", ">= 20"] -def test_mapping_colours_for_handles_missing_values(): - rgba = ThresholdScale("C", **COMFORT).mapping().colours_for([17, None, "x", 30]) - assert np.isnan(rgba[1]).all() and np.isnan(rgba[2]).all() - assert to_hex(rgba[3]) == "#ff0000" +def test_changing_the_palette_keeps_the_breaks(): + scale = ColourScale("Heat", [10, 20, 30], "viridis") + assert scale.colours() == palettes.sample("viridis", 4) + scale.cmap = "okabe_ito" + assert scale.thresholds == [10, 20, 30] and scale.colours() == palettes.sample("okabe_ito", 4) + scale.cmap = ["red", "green", "blue", "black"] + assert scale.colours()[0] == "#ff0000" + with pytest.raises(ColourScaleError, match="4 bands"): + scale.cmap = ["red", "green"] -# -- data passed in ---------------------------------------------------------- -def test_data_summary_ignores_unreadable_values(): - summary = DataSummary.from_data([1, 2, None, "n/a", float("nan"), 3, 10]) - assert summary.count == 4 and summary.minimum == 1 and summary.maximum == 10 - assert summary.histogram[0].sum() == 4 - with pytest.raises(ColourScaleError): - DataSummary.from_data([None, "x"]) +def test_value_range_follows_the_data_or_the_thresholds(): + scale = ColourScale("T", [10, 20], "viridis") + assert scale.value_range([12, 18]) == (12, 18) and scale.value_range([5, 5]) == (4.5, 5.5) + lo, hi = scale.value_range() + assert lo < 10 and hi > 20 +@pytest.mark.parametrize("kwargs,message", [ + (dict(thresholds=[]), "at least one"), + (dict(thresholds=[2, 1]), "increasing"), + (dict(thresholds=[1, 2], cmap=["red", "green"]), "3 bands"), + (dict(thresholds=[1], labels=["a"]), "one label per band"), + (dict(thresholds=[1], cmap=["red", "notacolour"]), "not a colour"), + (dict(thresholds=[1], cmap="no_such_map"), "Unknown colour map"), + (dict(thresholds=[1], name=" "), "needs a name"), +]) +def test_validation(kwargs, message): + with pytest.raises(ColourScaleError, match=message): + ColourScale(**{"name": "Bad", **kwargs}) + + +# -- suggesting thresholds ----------------------------------------------------- + def test_suggest_thresholds_methods(): data = np.concatenate([np.full(90, 20.0), np.linspace(20, 30, 10)]) assert suggest_thresholds([0, 100], 4, "equal") == [25, 50, 75] @@ -92,6 +100,20 @@ def test_suggest_thresholds_methods(): suggest_thresholds(data, 4, "quantile") q = suggest_thresholds(np.arange(100), 4, "quantile") assert len(q) == 3 and q[0] < q[1] < q[2] + assert suggest_thresholds([1, None, "x", float("nan"), 3], 2, "equal") == [2] + + +def test_log_thresholds_have_equal_ratios(): + thresholds = suggest_thresholds([1, 1000], 3, "log") + assert thresholds == pytest.approx([10, 100]) + spread = suggest_thresholds(np.geomspace(0.5, 4000, 50), 5, "log") + ratios = [b / a for a, b in zip(spread, spread[1:])] + assert len(spread) == 4 and ratios == pytest.approx([ratios[0]] * 3, rel=0.02) + for data in ([0, 10, 100], [-5, 10, 100]): + with pytest.raises(ColourScaleError, match="above zero"): + suggest_thresholds(data, 3, "log") + with pytest.raises(ColourScaleError, match="too narrow"): + suggest_thresholds([1.0, 1.001], 5, "log") @pytest.mark.parametrize("data,bands,expected", [ @@ -106,79 +128,61 @@ def test_nice_thresholds_fall_inside_the_data(data, bands, expected): assert all(min(data) < t < max(data) for t in thresholds) -def test_threshold_scale_from_data(): - scale = ThresholdScale.from_data("Loads", np.linspace(0, 95, 50), bands=4, method="nice", - palette="Okabe-Ito (colour-blind safe)", group="Loads") - assert scale.thresholds == [25, 50, 75] and scale.bands == 4 and scale.group == "Loads" - assert len(palette_colours("Traffic light", 7)) == 7 +# -- saved scales -------------------------------------------------------------- +def test_round_trip_through_dict(): + for scale in (ColourScale("Comfort", **COMFORT), ColourScale("Palette", [1, 2], cmap="ltc_maya")): + assert ColourScale.from_dict(json.loads(json.dumps(scale.to_dict()))).to_dict() == scale.to_dict() -# -- persistence ------------------------------------------------------------- -def test_round_trip_through_dict(): - for scale in (ThresholdScale("Comfort", **COMFORT), GradientScale.from_palette("G", "LTC Maya", bins=6)): - rebuilt = ColourScale.from_dict(json.loads(json.dumps(scale.to_dict()))) - assert type(rebuilt) is type(scale) and rebuilt.to_dict() == scale.to_dict() - - -def test_library_sets(tmp_path): - library = ColourScaleLibrary(tmp_path / "scales.json") - library.save(ThresholdScale("Comfort", **COMFORT)) - library.save(GradientScale.from_palette("Heat", "LTC Heatmap", group="Loads")) - library.save(ThresholdScale("Overheating", [26, 28], ["green", "orange", "red"], group="TM59")) - reopened = ColourScaleLibrary(tmp_path / "scales.json") - assert reopened.groups() == ["TM59", "Loads"] - assert reopened.names("TM59") == ["Comfort", "Overheating"] - assert reopened.get("Comfort").labels[-1] == "Hot" +def test_save_and_load(tmp_path): + path = tmp_path / "scales.json" + save_scale(ColourScale("Comfort", **COMFORT), path) + save_scale(ColourScale("Overheating", [26, 28], "RdYlGn_r"), path) + assert [s.name for s in load_scales(path)] == ["Comfort", "Overheating"] with pytest.raises(ColourScaleError, match="already exists"): - reopened.save(ThresholdScale("Comfort", **COMFORT)) - reopened.rename_group("TM59", "Overheating checks") - reopened.delete_group("Loads") - final = ColourScaleLibrary(tmp_path / "scales.json") - assert final.groups() == ["Overheating checks"] and len(final) == 2 + save_scale(ColourScale("Comfort", [1], "viridis"), path) + save_scale(ColourScale("Comfort", [1], "viridis"), path, overwrite=True) + assert load_scales(path)[-1].thresholds == [1] -def test_unreadable_entries_reported_and_kept(tmp_path): +def test_unreadable_entries_are_skipped_and_kept(tmp_path): path = tmp_path / "mixed.json" - path.write_text(json.dumps({"version": 2, "scales": [ - ThresholdScale("Good", [1], ["red", "blue"]).to_dict(), - {"type": "thresholds", "name": "Broken", "thresholds": [2, 1], "colours": ["a"]}, + path.write_text(json.dumps({"scales": [ + ColourScale("Good", [1], "viridis").to_dict(), + {"name": "Broken", "thresholds": [2, 1], "cmap": "viridis"}, ]}), encoding="utf-8") - library = ColourScaleLibrary(path) - assert library.names() == ["Good"] and "Broken" in library.problems[0] - library.save(ThresholdScale("New", [5], ["red", "blue"])) - names_on_disk = [e["name"] for e in json.loads(path.read_text(encoding="utf-8"))["scales"]] - assert "Broken" in names_on_disk # never silently deleted + assert [s.name for s in load_scales(path)] == ["Good"] + save_scale(ColourScale("New", [5], "viridis"), path) + assert "Broken" in [e["name"] for e in json.loads(path.read_text(encoding="utf-8"))["scales"]] -def test_corrupt_library_raises(tmp_path): - path = tmp_path / "bad.json" - path.write_text("{not json", encoding="utf-8") - with pytest.raises(ColourScaleError, match="Cannot read"): - ColourScaleLibrary(path) +def test_entries_without_thresholds_are_skipped(tmp_path): + path = tmp_path / "gradient.json" + path.write_text(json.dumps({"scales": [{"type": "gradient", "name": "Old gradient", "stops": [[0, "red"], [1, "blue"]]}]}), + encoding="utf-8") + assert load_scales(path) == [] -def test_palettes_are_valid(): - for name, colours in PALETTES.items(): - assert len(colours) >= 3, name - GradientScale.from_palette(name, name) +def test_older_threshold_entries_still_load(tmp_path): + path = tmp_path / "old.json" + path.write_text(json.dumps({"version": 1, "scales": [ + {"type": "thresholds", "name": "Old", "thresholds": [1], "colours": ["#000000", "#ffffff"], + "labels": None, "units": None, "group": "TM59"}, + ]}), encoding="utf-8") + assert load_scales(path)[0].colours() == ["#000000", "#ffffff"] + +def test_corrupt_file_raises(tmp_path): + path = tmp_path / "bad.json" + path.write_text("{not json", encoding="utf-8") + with pytest.raises(ColourScaleError, match="Cannot read"): + load_scales(path) -def test_palettes_registered_as_colour_maps(): - from matplotlib import colormaps - from python_toolkit.plot.colour_scales import PALETTE_CMAPS, palette_names - for name in PALETTE_CMAPS.values(): - assert name in colormaps and f"{name}_r" in colormaps - names = palette_names() - assert names[:len(PALETTES)] == list(PALETTES) and "magma" in names and "okabe_ito" not in names - assert palette_colours("magma", 3)[0] == "#000004" - with pytest.raises(ColourScaleError, match="Unknown palette"): - palette_colours("no such map", 3) - - -def test_to_colormap_keeps_band_widths(): - scale = ThresholdScale("T", [10, 30], ["#0000ff", "#00ff00", "#ff0000"]) - cmap = scale.to_colormap(np.array([0, 40])) - colours = [to_hex(cmap(x)) for x in (0.1, 0.5, 0.9)] - assert colours == ["#0000ff", "#00ff00", "#ff0000"] and cmap.name == "T" +@pytest.mark.parametrize("method", ["equal", "quantile", "nice", "log"]) +@pytest.mark.parametrize("bands", [2, 3, 4, 5, 6, 8]) +def test_suggestions_always_give_the_number_of_bands_asked_for(method, bands): + data = np.random.default_rng(1).normal(22, 3, 300) + assert len(suggest_thresholds(data, bands, method)) == bands - 1 + assert len(suggest_thresholds([16, 30], bands, "nice")) == bands - 1 From ef4cb4d092e0fcee6a06c3c08ab39737d25d805d Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Wed, 28 Oct 2026 17:43:15 +0000 Subject: [PATCH 3/8] improved builder objects --- .../windows/colour_scale_builder.py | 7 +- .../src/python_toolkit/plot/colour_scales.py | 66 ++++++++++++++++--- .../src/python_toolkit/plot/palettes.py | 3 + .../Python/tests/test_colour_scale_builder.py | 24 +++---- .../Python/tests/test_colour_scales.py | 31 +++++---- 5 files changed, 90 insertions(+), 41 deletions(-) diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py index 86dc896..bb74fea 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -31,7 +31,7 @@ from python_toolkit.bhom_tkinter.widgets.spinbox import Spinbox from python_toolkit.bhom_tkinter.widgets.validated_entry_box import ValidatedEntryBox from python_toolkit.bhom_tkinter.theming.scaling import scale as scale_px -from python_toolkit.plot import palettes +from python_toolkit.plot import colour_scales, palettes from python_toolkit.plot.colour_scales import ( SUGGESTION_METHODS, ColourScale, @@ -39,10 +39,9 @@ clean_data, load_scales, save_scale, - suggest_thresholds, ) -MAX_BANDS = 12 +MAX_BANDS = 24 TYPING_DELAY = 700 # ms to wait after the last keystroke, so "22" is not read as "2" first PLOT_WIDTH = 560 # the plot, the controls and the band table all share this width ERROR_COLOUR = "#c0392b" @@ -206,7 +205,7 @@ def _run_auto_suggest(self) -> None: def _suggest(self) -> None: try: bands = int(self.band_count.get()) - thresholds = suggest_thresholds(self.values, bands, self.method.get()) + thresholds = colour_scales.thresholds(self.values, bands, self.method.get()) except (ColourScaleError, ValueError) as e: self.status.set(str(e)) return diff --git a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py index 7d5d035..5244735 100644 --- a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py +++ b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py @@ -29,7 +29,8 @@ from python_toolkit.plot import palettes LIBRARY_FILE = Path.home() / ".bhom" / "colour_scales.json" -SUGGESTION_METHODS = ("equal", "quantile", "nice", "log") +SUGGESTION_METHODS = ("equal", "quantile", "jenks", "nice", "log") +JENKS_MAX_VALUES = 2000 # larger data is thinned (evenly through its sorted values) before the search class ColourScaleError(ValueError): @@ -90,9 +91,15 @@ def value_range(self, data: Optional[Iterable] = None) -> Tuple[float, float]: lo, hi = self.thresholds[0] - pad, self.thresholds[-1] + pad return (lo - 0.5, hi + 0.5) if lo == hi else (lo, hi) - def mapping(self) -> Tuple[Colormap, BoundaryNorm]: - """The colormap and normaliser to colour any data with; values beyond the ends take the end colours.""" - edges = [self.thresholds[0] - 1] + self.thresholds + [self.thresholds[-1] + 1] + def mapping(self, data: Optional[Iterable] = None) -> Tuple[Colormap, BoundaryNorm]: + """The colormap and normaliser to colour any data with; values beyond the ends take the end colours. + + Pass the data so the end bands run to its minimum and maximum: a colour bar drawn with + `spacing="proportional"` then shows every band at its true width, as the builder preview does.""" + lo, hi = self.value_range(data) + t = self.thresholds + first_gap, last_gap = (t[1] - t[0], t[-1] - t[-2]) if len(t) > 1 else (1.0, 1.0) + edges = [lo if lo < t[0] else t[0] - first_gap] + t + [hi if hi > t[-1] else t[-1] + last_gap] return ListedColormap(self.colours(), name=self.name), BoundaryNorm(edges, self.bands, clip=True) def band_labels(self) -> List[str]: @@ -120,11 +127,12 @@ def __repr__(self) -> str: # Suggesting thresholds from data # --------------------------------------------------------------------------- -def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List[float]: +def thresholds(data: Iterable, bands: int, method: str = "nice") -> List[float]: """Inner boundaries splitting the data into `bands` bands. equal: equal-width bands across the data range quantile: roughly the same number of values in each band + jenks: natural breaks; the bands that minimise the spread of values within each band nice: equal-width bands on rounded 1 / 2 / 5 x 10^n steps log: bands of equal ratio (each break a fixed multiple of the last), rounded to 3 significant figures; needs every value above zero @@ -148,6 +156,8 @@ def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List if len(unique) < bands - 1: raise ColourScaleError("Too many repeated values for that many quantile bands; use fewer bands.") return unique + if method == "jenks": + return _jenks_thresholds(values, bands) if method == "log": if lo <= 0: raise ColourScaleError("Logarithmic breaks need every value above zero; use another break method.") @@ -158,11 +168,50 @@ def suggest_thresholds(data: Iterable, bands: int, method: str = "nice") -> List return _nice_thresholds(lo, hi, bands - 1) +def _jenks_thresholds(values: np.ndarray, bands: int) -> List[float]: + """Fisher-Jenks natural breaks: the split into `bands` runs of sorted values with the least + total squared deviation from each run's mean. Each break is the lowest value of the band above it.""" + ordered = np.sort(values) + if ordered.size > JENKS_MAX_VALUES: + ordered = ordered[np.linspace(0, ordered.size - 1, JENKS_MAX_VALUES).round().astype(int)] + x, counts = np.unique(ordered, return_counts=True) + n = x.size + if n < bands: + raise ColourScaleError("Too few distinct values for that many natural-break bands; use fewer bands.") + + w = counts.astype(float) + cw, cwx, cwx2 = (np.concatenate([[0.0], np.cumsum(a)]) for a in (w, w * x, w * x * x)) + + def cost(starts: np.ndarray, end: int) -> np.ndarray: + """Squared deviation of x[start:end + 1] about its mean, for each start.""" + sw, swx, swx2 = cw[end + 1] - cw[starts], cwx[end + 1] - cwx[starts], cwx2[end + 1] - cwx2[starts] + return swx2 - swx * swx / sw + + best = np.full((bands, n), np.inf) + first = np.zeros((bands, n), dtype=int) # where the last band starts, for the best split of x[:j + 1] + for j in range(n): + best[0, j] = cost(np.array([0]), j)[0] + for k in range(1, bands): + for j in range(k, n): + starts = np.arange(k, j + 1) + total = best[k - 1, starts - 1] + cost(starts, j) + pick = int(np.argmin(total)) + best[k, j], first[k, j] = total[pick], starts[pick] + + cuts, end = [], n - 1 + for k in range(bands - 1, 0, -1): + start = int(first[k, end]) + cuts.append(float(x[start])) + end = start - 1 + return cuts[::-1] + + def _nice_thresholds(lo: float, hi: float, wanted: int) -> List[float]: """Rounded breaks (multiples of 1, 2, 2.5 or 5 x 10^n) strictly inside the data range. - Picks the step with the fewest breaks that is still at least `wanted`, then keeps the middle `wanted` - of them, so every band contains data rather than extending beyond it.""" + Picks the step with the fewest breaks that is still at least `wanted`, then keeps `wanted` of them spread + evenly from the first to the last, so every band contains data and the end bands stay small. Where the + step does not divide evenly, some bands are two steps wide.""" exponent = math.floor(math.log10((hi - lo) / (wanted + 1))) best = None for power in (exponent - 1, exponent, exponent + 1): @@ -177,8 +226,7 @@ def _nice_thresholds(lo: float, hi: float, wanted: int) -> List[float]: if best is None: # range too narrow for rounded breaks return [float(v) for v in np.linspace(lo, hi, wanted + 2)[1:-1]] inner = best[1] - start = max(len(inner) - wanted, 0) // 2 - return inner[start:start + wanted] + return [inner[i] for i in np.linspace(0, len(inner) - 1, wanted).round().astype(int)] # --------------------------------------------------------------------------- diff --git a/Python_Engine/Python/src/python_toolkit/plot/palettes.py b/Python_Engine/Python/src/python_toolkit/plot/palettes.py index 160b02b..35da77a 100644 --- a/Python_Engine/Python/src/python_toolkit/plot/palettes.py +++ b/Python_Engine/Python/src/python_toolkit/plot/palettes.py @@ -21,15 +21,18 @@ "ltc_heatmap": ("continuous", False, ["#000004", "#51127c", "#b63679", "#fb8861", "#fcffa4"]), "ltc_maya": ("continuous", False, ["#5c8286", "#a1b18c", "#e7cca6", "#d98f79", "#b35b5a"]), "ltc_paloma": ("continuous", False, ["#1a2a40", "#456a73", "#82a69d", "#d9ccb6", "#bf8865"]), + "parula": ("continuous", False, ["#3e26a8", "#484cf0", "#337afd", "#21a3e3", "#14beb8", "#5ecd74", "#cbc128", "#fdcb32", "#f9fb15"]), } # matplotlib colour maps by kind; the toolkit palettes are added below. KINDS = { "categorical": ["Accent", "Dark2", "Paired", "Pastel1", "Pastel2", "Set1", "Set2", "Set3", "tab10", "tab20", "tab20b", "tab20c"], + "continuous": ["viridis", "plasma", "inferno", "magma", "cividis", "turbo", "Blues", "Greens", "Greys", "Oranges", "Purples", "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd", "coolwarm", "seismic", "Spectral", "RdYlBu", "RdYlGn", "twilight", "twilight_shifted", "hsv"], + # perceptually uniform maps; matplotlib's own, so safe for the common colour vision deficiencies "colourblind": ["viridis", "cividis", "plasma", "inferno", "magma"], } diff --git a/Python_Engine/Python/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py index 40dcbb7..e0b2fdd 100644 --- a/Python_Engine/Python/tests/test_colour_scale_builder.py +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -48,7 +48,7 @@ def library(tmp_path): def test_builder_suggests_bands_from_data(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), units="degC", library_path=library) scale = builder.current_scale() - assert scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + assert scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) assert scale.units == "degC" and scale.cmap == "viridis" assert "200 values from 16 to 30 degC" in builder.data_text.get() @@ -111,7 +111,7 @@ def test_builder_starts_from_a_palette_and_recolours(host, library): builder.palette.set("traffic_light") builder._recolour() scale = builder.current_scale() - assert scale.cmap == "traffic_light" and scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + assert scale.cmap == "traffic_light" and scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) builder._band_rows[0]["colour"].set("#123456") assert builder.current_scale().cmap[0] == "#123456" # a hand-picked colour makes it an explicit list @@ -139,13 +139,13 @@ def test_end_to_end_palette_to_saved_scale_to_colours(host, library): builder._save() scale = load_scales(library)[0] - assert scale.cmap == "okabe_ito" and scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) + assert scale.cmap == "okabe_ito" and scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) cmap, norm = scale.mapping() colours = {to_hex(cmap(norm(v))) for v in data} assert colours == set(palettes.sample("okabe_ito", 5)) # every band is used, in the palette's colours scale.cmap = "viridis" # swap the colours; the breaks hold - assert scale.thresholds == pytest.approx([17.5, 20, 22.5, 25]) and scale.colours() == palettes.sample("viridis", 5) + assert scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) and scale.colours() == palettes.sample("viridis", 5) def test_bands_and_breaks_update_the_scale_without_a_button(host, library): @@ -213,11 +213,11 @@ def test_thresholds_spin_in_round_steps(host, library): def test_split_a_band_adds_one_between_its_ends(host, library): - builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) # breaks 17.5 20 22.5 25 + builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) # breaks 17.5 20 25 27.5 builder._band_rows[1]["label"].set("Cool") builder._split_band(1) # the band 17.5 to 20 becomes 17.5 to 18.75 and 18.75 to 20 scale = builder.current_scale() - assert scale.thresholds == pytest.approx([17.5, 18.75, 20, 22.5, 25]) and scale.bands == 6 + assert scale.thresholds == pytest.approx([17.5, 18.75, 20, 25, 27.5]) and scale.bands == 6 assert scale.labels == [None, "Cool", None, None, None, None] # the label stays with the lower half assert builder.band_count.get() == 6 assert scale.cmap == "viridis" # still a palette, spread over six bands @@ -227,8 +227,8 @@ def test_split_the_open_ends_against_the_data(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) builder._split_band(0) # below 17.5: split against the data minimum, 16 assert builder.current_scale().thresholds[:2] == pytest.approx([16.75, 17.5]) - builder._split_band(len(builder._band_rows) - 1) # 25 and above: split against the data maximum, 30 - assert builder.current_scale().thresholds[-1] == pytest.approx(27.5) + builder._split_band(len(builder._band_rows) - 1) # 27.5 and above: split against the data maximum, 30 + assert builder.current_scale().thresholds[-1] == pytest.approx(28.75) def test_remove_a_band_merges_its_range_into_the_next(host, library): @@ -238,10 +238,10 @@ def test_remove_a_band_merges_its_range_into_the_next(host, library): builder._band_rows[2]["colour"].set("#123456") # a hand-picked colour, which makes colours explicit builder._remove_band(1) scale = builder.current_scale() - assert scale.thresholds == pytest.approx([17.5, 22.5, 25]) and scale.labels == ["a", "c", "d", "e"] # "c" now starts at 17.5 + assert scale.thresholds == pytest.approx([17.5, 25, 27.5]) and scale.labels == ["a", "c", "d", "e"] # "c" now starts at 17.5 assert scale.colours()[1] == "#123456" builder._remove_band(len(builder._band_rows) - 1) # the last band: the one before it becomes open-ended - assert builder.current_scale().thresholds == pytest.approx([17.5, 22.5]) and builder.current_scale().labels == ["a", "c", "d"] + assert builder.current_scale().thresholds == pytest.approx([17.5, 25]) and builder.current_scale().labels == ["a", "c", "d"] def test_bands_cannot_go_below_two_or_above_the_maximum(host, library): @@ -251,11 +251,11 @@ def test_bands_cannot_go_below_two_or_above_the_maximum(host, library): assert "disabled" in builder._band_rows[0]["remove"].state() builder._remove_band(0) assert len(builder._band_rows) == 2 - builder.band_count.set(12) + builder.band_count.set(24) builder._run_auto_suggest() assert "disabled" in builder._band_rows[0]["split"].state() builder._split_band(0) - assert len(builder._band_rows) == 12 + assert len(builder._band_rows) == 24 def test_split_refuses_a_bad_threshold_without_changing_the_table(host, library): diff --git a/Python_Engine/Python/tests/test_colour_scales.py b/Python_Engine/Python/tests/test_colour_scales.py index 247b8d2..ae0eff0 100644 --- a/Python_Engine/Python/tests/test_colour_scales.py +++ b/Python_Engine/Python/tests/test_colour_scales.py @@ -5,13 +5,12 @@ from matplotlib import colormaps from matplotlib.colors import to_hex -from python_toolkit.plot import palettes +from python_toolkit.plot import colour_scales, palettes from python_toolkit.plot.colour_scales import ( ColourScale, ColourScaleError, load_scales, save_scale, - suggest_thresholds, ) COMFORT = dict(thresholds=[18, 21, 24], cmap=["#0000ff", "#00ffff", "#00ff00", "#ff0000"], @@ -92,38 +91,38 @@ def test_validation(kwargs, message): # -- suggesting thresholds ----------------------------------------------------- -def test_suggest_thresholds_methods(): +def test_thresholds_methods(): data = np.concatenate([np.full(90, 20.0), np.linspace(20, 30, 10)]) - assert suggest_thresholds([0, 100], 4, "equal") == [25, 50, 75] - assert suggest_thresholds([0.3, 9.7], 5, "nice") == [2, 4, 6, 8] + assert colour_scales.thresholds([0, 100], 4, "equal") == [25, 50, 75] + assert colour_scales.thresholds([0.3, 9.7], 5, "nice") == [2, 4, 6, 8] with pytest.raises(ColourScaleError, match="repeated values"): - suggest_thresholds(data, 4, "quantile") - q = suggest_thresholds(np.arange(100), 4, "quantile") + colour_scales.thresholds(data, 4, "quantile") + q = colour_scales.thresholds(np.arange(100), 4, "quantile") assert len(q) == 3 and q[0] < q[1] < q[2] - assert suggest_thresholds([1, None, "x", float("nan"), 3], 2, "equal") == [2] + assert colour_scales.thresholds([1, None, "x", float("nan"), 3], 2, "equal") == [2] def test_log_thresholds_have_equal_ratios(): - thresholds = suggest_thresholds([1, 1000], 3, "log") + thresholds = colour_scales.thresholds([1, 1000], 3, "log") assert thresholds == pytest.approx([10, 100]) - spread = suggest_thresholds(np.geomspace(0.5, 4000, 50), 5, "log") + spread = colour_scales.thresholds(np.geomspace(0.5, 4000, 50), 5, "log") ratios = [b / a for a, b in zip(spread, spread[1:])] assert len(spread) == 4 and ratios == pytest.approx([ratios[0]] * 3, rel=0.02) for data in ([0, 10, 100], [-5, 10, 100]): with pytest.raises(ColourScaleError, match="above zero"): - suggest_thresholds(data, 3, "log") + colour_scales.thresholds(data, 3, "log") with pytest.raises(ColourScaleError, match="too narrow"): - suggest_thresholds([1.0, 1.001], 5, "log") + colour_scales.thresholds([1.0, 1.001], 5, "log") @pytest.mark.parametrize("data,bands,expected", [ - ([16, 30], 5, [17.5, 20, 22.5, 25]), + ([16, 30], 5, [17.5, 20, 25, 27.5]), ([8, 24], 4, [10, 15, 20]), ([0, 95], 4, [25, 50, 75]), ([1000, 250000], 5, [50000, 100000, 150000, 200000]), ]) def test_nice_thresholds_fall_inside_the_data(data, bands, expected): - thresholds = suggest_thresholds(data, bands, "nice") + thresholds = colour_scales.thresholds(data, bands, "nice") assert thresholds == pytest.approx(expected) assert all(min(data) < t < max(data) for t in thresholds) @@ -184,5 +183,5 @@ def test_corrupt_file_raises(tmp_path): @pytest.mark.parametrize("bands", [2, 3, 4, 5, 6, 8]) def test_suggestions_always_give_the_number_of_bands_asked_for(method, bands): data = np.random.default_rng(1).normal(22, 3, 300) - assert len(suggest_thresholds(data, bands, method)) == bands - 1 - assert len(suggest_thresholds([16, 30], bands, "nice")) == bands - 1 + assert len(colour_scales.thresholds(data, bands, method)) == bands - 1 + assert len(colour_scales.thresholds([16, 30], bands, "nice")) == bands - 1 From 7cd18e465766647ffeaa6758c68f98899ecf1433 Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Tue, 10 Nov 2026 12:18:09 +0000 Subject: [PATCH 4/8] connected new scales with the cmap selector --- .../bhom_tkinter/widgets/cmap_selector.py | 141 +++++++++++++++++- .../windows/colour_scale_builder.py | 8 +- .../src/python_toolkit/plot/colour_scales.py | 35 ++++- .../src/python_toolkit/plot/palettes.py | 2 +- .../Python/tests/test_colour_scale_builder.py | 71 +++++++++ .../Python/tests/test_colour_scales.py | 23 +++ 6 files changed, 267 insertions(+), 13 deletions(-) diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index 446ac2d..c073ce0 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py @@ -1,15 +1,17 @@ """Colormap selector widget with embedded matplotlib preview.""" -from typing import Dict, List, Optional, Literal, Union -from tkinter import ttk +from pathlib import Path +from typing import Dict, Iterable, List, Optional, Literal, Union +from tkinter import messagebox, ttk import tkinter as tk import matplotlib as mpl -from matplotlib.colors import Colormap, ListedColormap +from matplotlib.colors import BoundaryNorm, Colormap, ListedColormap from python_toolkit.plot.cmap_sample import cmap_sample_plot from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget from python_toolkit.bhom_tkinter.widgets._packing_options import PackingOptions from python_toolkit.plot import palettes +from python_toolkit.plot.colour_scales import ColourScale, ColourScaleError, clean_data, delete_scale, load_scales from python_toolkit.bhom.analytics import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.theming.scaling import scale_pad @@ -37,6 +39,10 @@ def __init__( default_cmap: Optional[CmapInput] = None, plot_size: tuple[int, int] = (400, 50), dropdown_position: Literal["n", "e", "s", "w"] = "n", + include_scales: bool = False, + data: Optional[Iterable] = None, + units: Optional[str] = None, + scales_path: Optional[Path] = None, **kwargs ) -> None: """ @@ -58,12 +64,24 @@ def __init__( dropdown_position: Position of the dropdown relative to the preview swatch. "n" = above, "s" = below, "w" = left, "e" = right. + include_scales: List the saved colour scales (see `python_toolkit.plot.colour_scales`) + as "Name (scale)" entries, with buttons to build, edit and delete them. + Use `get_scale()` and `get_norm()` to colour data with the selected scale. + data: Values the scales will colour; passed to the scale builder for its + histogram and break suggestions, and used to stretch the end bands. + units: Units of `data`, stored with new scales. + scales_path: Saved scales file (defaults to the user's saved scales). **kwargs: Additional Frame options. """ super().__init__(parent, **kwargs) self.cmap_bins = cmap_bins self.plot_size = plot_size + self.include_scales = include_scales + self.data = None if data is None else clean_data(data) + self.units = units + self.scales_path = scales_path + self._scales: Dict[str, ColourScale] = {} # combobox label -> saved scale # Registry of custom (non-matplotlib-named) colormaps: label → Colormap self._custom_cmaps: Dict[str, Colormap] = {} @@ -79,7 +97,8 @@ def __init__( self.cmap_frame.columnconfigure(0, weight=1) self.cmap_frame.rowconfigure(0, weight=1) - content = ttk.Frame(self.cmap_frame, width=plot_size[0], height=plot_size[1]) + content = ttk.Frame(self.cmap_frame, width=plot_size[0], + height=plot_size[1] + (scale_pad(34) if include_scales else 0)) content.grid(row=0, column=0, padx=scale_pad(0), pady=scale_pad(4), sticky=self._grid_sticky) content.grid_propagate(False) @@ -104,6 +123,9 @@ def __init__( ) self.cmap_combobox.pack(side=tk.TOP, anchor=self._pack_anchor, padx=scale_pad(0)) self.cmap_combobox.bind("<>", self._on_cmap_selected) + if include_scales: + self._build_scale_buttons(header) + self.colormap_var.trace_add("write", lambda *_: self._update_scale_buttons()) fill_mode: Literal["x", "y"] = "y" if is_horizontal else "x" self.figure_widget = FigureContainer( @@ -122,6 +144,9 @@ def __init__( current_colormaps = self._preset_colormaps(self.cmap_set_var.get()) self._populate_cmap_list(current_colormaps) + if include_scales: + self._refresh_scales() + current_colormaps = list(self.cmap_combobox["values"]) # Resolve default_cmap: may itself be a Colormap object or colour list self._default_label = self._resolve_default_label(default_cmap, current_colormaps) @@ -330,6 +355,93 @@ def get_cmap(self) -> Optional[Colormap]: return mpl.colormaps.get(name) + # ── saved colour scales ──────────────────────────────────────────────── + + @staticmethod + def _scale_label(name: str) -> str: + return f"{name} (scale)" + + def _build_scale_buttons(self, parent: ttk.Frame) -> None: + row = ttk.Frame(parent) + row.pack(side=tk.TOP, anchor=self._pack_anchor, pady=(4, 0)) + self.new_scale_button = ttk.Button(row, text="New scale…", command=lambda: self._open_builder(None)) + self.edit_scale_button = ttk.Button(row, text="Edit…", command=self._edit_scale) + self.delete_scale_button = ttk.Button(row, text="Delete", command=self._delete_scale) + for button in (self.new_scale_button, self.edit_scale_button, self.delete_scale_button): + button.pack(side=tk.LEFT, padx=(0, 4)) + self._update_scale_buttons() + + def _update_scale_buttons(self) -> None: + state = ["!disabled"] if self.get_scale() is not None else ["disabled"] + self.edit_scale_button.state(state) + self.delete_scale_button.state(state) + + def _refresh_scales(self, select: Optional[str] = None) -> None: + """Reload the saved scales into the dropdown, keeping the selection (or selecting the scale named `select`).""" + previous = self.colormap_var.get() + for label in self._scales: + self._custom_cmaps.pop(label, None) + try: + scales = load_scales(self.scales_path) + except ColourScaleError as e: # an unreadable file must not break the selector + CONSOLE_LOGGER.warning(str(e)) + scales = [] + palette_values = [v for v in self.cmap_combobox["values"] if v not in self._scales] + self._scales = {self._scale_label(s.name): s for s in scales} + for label, scale in self._scales.items(): + self._custom_cmaps[label] = scale.mapping(self.data)[0] + self._populate_cmap_list(palette_values + list(self._scales)) + target = self._scale_label(select) if select else previous + if target in self.cmap_combobox["values"]: + self.colormap_var.set(target) + self._update_cmap_sample() + elif previous: # the selected scale was deleted + self.colormap_var.set(palette_values[0] if palette_values else "") + self._update_cmap_sample() + + def _open_builder(self, scale: Optional[ColourScale]) -> None: + """Open the scale builder to make a new scale, or edit `scale`; the saved scale is then selected.""" + # imported here: the window imports the widgets package, so a top-level import would be circular + from python_toolkit.bhom_tkinter.windows.colour_scale_builder import ColourScaleBuilder + + current = self.colormap_var.get() + builder = ColourScaleBuilder( + self.winfo_toplevel(), data=self.data, units=self.units, scale=scale, library_path=self.scales_path, + palette=current if current in palettes.names() else None, on_save=self._on_scale_saved) + builder.run() + + def _on_scale_saved(self, scale: ColourScale) -> None: + self._refresh_scales(select=scale.name) + self._fire_on_change(self.get()) + + def _edit_scale(self) -> None: + scale = self.get_scale() + if scale is not None: + self._open_builder(scale) + + def _delete_scale(self) -> None: + scale = self.get_scale() + if scale is None or not messagebox.askyesno("Delete colour scale", f"Delete the saved scale '{scale.name}'?"): + return + try: + delete_scale(scale.name, self.scales_path) + except (ColourScaleError, OSError) as e: + messagebox.showerror("Delete colour scale", str(e)) + return + self._refresh_scales() + self._fire_on_change(self.get()) + + def get_scale(self) -> Optional[ColourScale]: + """The selected saved colour scale, or None when a plain palette is selected.""" + return self._scales.get(self.colormap_var.get()) + + def get_norm(self) -> Optional[BoundaryNorm]: + """The normaliser for the selected scale (thresholds in data units), or None for a plain palette. + + Colour data with `get_cmap()` and `get_norm()` together; the end bands run to the `data` given.""" + scale = self.get_scale() + return scale.mapping(self.data)[1] if scale is not None else None + def add_cmap(self, cmap: CmapInput, label: Optional[str] = None) -> Optional[str]: """Dynamically add a new colormap entry to the selector. @@ -394,6 +506,9 @@ def set(self, value: Optional[CmapInput]) -> None: self.colormap_var.set("") return + if isinstance(value, ColourScale): + value = self._scale_label(value.name) + if isinstance(value, str): if value in self.cmap_combobox["values"]: self.colormap_var.set(value) @@ -525,6 +640,24 @@ def validate(self) -> tuple[bool, Optional[str], Optional[Literal['info', 'warni selector_dynamic.add_cmap(["#003366", "#0066cc", "#99ccff"], label="brand_blue") selector_dynamic.add_cmap(custom_listed) + # Example 6 — saved colour scales: build, edit and delete scales from sample data + import numpy as np + import tempfile + + selector_scales = CmapSelector( + parent_container, + cmap_set="colourblind", + include_scales=True, + data=np.random.default_rng(1).normal(22, 3, 300), + units="degC", + scales_path=Path(tempfile.gettempdir()) / "cmap_selector_demo_scales.json", # not your saved scales + item_title="6. Colour scales", + helper_text="New scale... opens the builder; saved scales appear as 'Name (scale)'.", + build_options=PackingOptions(fill="both", expand=True), + plot_size=(400, 40), + ) + selector_scales.build() + root.mainloop() # After mainloop — demonstrate get() vs get_cmap() return types diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py index bb74fea..9fb0a99 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -356,7 +356,11 @@ def current_scale(self) -> ColourScale: return ColourScale(name, thresholds, cmap, labels if any(labels) else None, self.units) def _unused_name(self, base: str) -> str: - names = {s.name for s in load_scales(self.library_path)} + try: + names = {s.name for s in load_scales(self.library_path)} + except ColourScaleError as e: # an unreadable library must not stop the window opening; saving reports it + CONSOLE_LOGGER.warning(str(e)) + names = set() n = 1 name = base while name in names: @@ -368,7 +372,7 @@ def _save(self) -> None: """Validate, save to the library and close; errors are shown in a pop-up and stay in the window.""" try: scale = self.current_scale() - save_scale(scale, self.library_path, overwrite=self.editing is not None and self.editing.name == scale.name) + save_scale(scale, self.library_path, replaces=self.editing.name if self.editing else None) except (ColourScaleError, OSError) as e: message = str(e) if "already exists" in message: diff --git a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py index 5244735..0575eb4 100644 --- a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py +++ b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py @@ -244,16 +244,36 @@ def load_scales(path: Optional[Path] = None) -> List[ColourScale]: return scales -def save_scale(scale: ColourScale, path: Optional[Path] = None, overwrite: bool = False) -> None: - """Add a scale to the saved file; an existing name is only replaced with `overwrite`.""" +def save_scale(scale: ColourScale, path: Optional[Path] = None, overwrite: bool = False, + replaces: Optional[str] = None) -> None: + """Add a scale to the saved file; an existing name is only replaced with `overwrite`. + + `replaces` is the saved name this scale is an edit of: that entry is replaced (so a renamed + scale does not leave its old name behind) without needing `overwrite`.""" path = Path(path or LIBRARY_FILE) entries = _read(path) - others = [e for e in entries if e.get("name") != scale.name] - if len(others) < len(entries) and not overwrite: + others = [e for e in entries if e.get("name") not in (scale.name, replaces)] + clash = scale.name != replaces and any(e.get("name") == scale.name for e in entries) + if clash and not overwrite: raise ColourScaleError(f"A scale named '{scale.name}' already exists.") + _write(path, others + [scale.to_dict()]) + + +def delete_scale(name: str, path: Optional[Path] = None) -> bool: + """Remove a saved scale by name; False if there was none of that name.""" + path = Path(path or LIBRARY_FILE) + entries = _read(path) + others = [e for e in entries if e.get("name") != name] + if len(others) == len(entries): + return False + _write(path, others) + return True + + +def _write(path: Path, entries: List[Dict[str, Any]]) -> None: path.parent.mkdir(parents=True, exist_ok=True) tmp = path.with_suffix(".tmp") - tmp.write_text(json.dumps({"version": 1, "scales": others + [scale.to_dict()]}, indent=2), encoding="utf-8") + tmp.write_text(json.dumps({"version": 1, "scales": entries}, indent=2), encoding="utf-8") tmp.replace(path) @@ -279,7 +299,10 @@ def clean_data(data: Optional[Iterable]) -> np.ndarray: """Finite float values from any iterable; None, NaN and non-numbers are dropped.""" if data is None: return np.empty(0) - numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) + try: # fast path: already numeric (or numeric strings) + numbers = np.ravel(np.asarray(data if hasattr(data, "__len__") else list(data), dtype=float)) + except (TypeError, ValueError): # mixed input: keep the numbers, drop the rest + numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) return numbers[np.isfinite(numbers)] diff --git a/Python_Engine/Python/src/python_toolkit/plot/palettes.py b/Python_Engine/Python/src/python_toolkit/plot/palettes.py index 35da77a..1431f46 100644 --- a/Python_Engine/Python/src/python_toolkit/plot/palettes.py +++ b/Python_Engine/Python/src/python_toolkit/plot/palettes.py @@ -32,7 +32,7 @@ "continuous": ["viridis", "plasma", "inferno", "magma", "cividis", "turbo", "Blues", "Greens", "Greys", "Oranges", "Purples", "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd", "coolwarm", "seismic", "Spectral", "RdYlBu", "RdYlGn", "twilight", "twilight_shifted", "hsv"], - + # perceptually uniform maps; matplotlib's own, so safe for the common colour vision deficiencies "colourblind": ["viridis", "cividis", "plasma", "inferno", "magma"], } diff --git a/Python_Engine/Python/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py index e0b2fdd..7bf2400 100644 --- a/Python_Engine/Python/tests/test_colour_scale_builder.py +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -263,3 +263,74 @@ def test_split_refuses_a_bad_threshold_without_changing_the_table(host, library) builder._band_rows[0]["upper"].set("warm") builder._split_band(1) assert len(builder._band_rows) == 5 and "not a number" in builder.status.get() + + +def test_builder_opens_with_an_unreadable_library(host, tmp_path): + path = tmp_path / "scales.json" + path.write_text("{not json", encoding="utf-8") + builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library_path=path) + assert builder.name.get() == "New scale" + + +def _scales_selector(host, library, data=None): + return CmapSelector(host.content_frame, include_scales=True, scales_path=library, data=data, units="degC") + + +def test_selector_lists_saved_scales_with_their_norm(host, library): + save_scale(ColourScale("Comfort", [18, 21, 24], "coolwarm"), library) + data = np.linspace(10, 30, 50) + selector = _scales_selector(host, library, data) + assert "Comfort (scale)" in selector.cmap_combobox["values"] + assert selector.get_scale() is None and selector.get_norm() is None # a plain palette is selected + selector.set("Comfort (scale)") + assert selector.get_scale().name == "Comfort" + norm = selector.get_norm() + assert list(norm.boundaries[1:-1]) == [18, 21, 24] and norm.boundaries[0] == 10 and norm.boundaries[-1] == 30 + assert len(selector.get_cmap().colors) == 4 + + +def test_selector_scale_buttons_follow_the_selection(host, library): + save_scale(ColourScale("Comfort", [18, 21, 24], "coolwarm"), library) + selector = _scales_selector(host, library) + assert selector.edit_scale_button.instate(["disabled"]) and selector.delete_scale_button.instate(["disabled"]) + selector.set("Comfort (scale)") + assert selector.edit_scale_button.instate(["!disabled"]) and selector.delete_scale_button.instate(["!disabled"]) + selector.set("viridis") + assert selector.edit_scale_button.instate(["disabled"]) + + +def test_selector_builds_edits_and_deletes_scales(host, library, monkeypatch): + from python_toolkit.bhom_tkinter.widgets import cmap_selector + + data = np.linspace(16, 30, 100) + selector = _scales_selector(host, library, data) + changes = [] + selector.on_change = changes.append + + # a new scale made in the builder is listed and selected + def new_scale(self): + self.name.set("Mine") + self._save() + + monkeypatch.setattr(ColourScaleBuilder, "run", new_scale) + selector.new_scale_button.invoke() + assert selector.get_scale().name == "Mine" + + # editing it and renaming it replaces the entry + def rename(self): + self.name.set("Renamed") + self._save() + + monkeypatch.setattr(ColourScaleBuilder, "run", rename) + selector.edit_scale_button.invoke() + assert selector.get_scale().name == "Renamed" + assert [s.name for s in load_scales(library)] == ["Renamed"] + assert "Mine (scale)" not in selector.cmap_combobox["values"] + + # deleting asks first, then falls back to a palette + monkeypatch.setattr(cmap_selector.messagebox, "askyesno", lambda *a, **k: False) + selector.delete_scale_button.invoke() + assert selector.get_scale() is not None + monkeypatch.setattr(cmap_selector.messagebox, "askyesno", lambda *a, **k: True) + selector.delete_scale_button.invoke() + assert selector.get_scale() is None and selector.get() and load_scales(library) == [] diff --git a/Python_Engine/Python/tests/test_colour_scales.py b/Python_Engine/Python/tests/test_colour_scales.py index ae0eff0..1a8598b 100644 --- a/Python_Engine/Python/tests/test_colour_scales.py +++ b/Python_Engine/Python/tests/test_colour_scales.py @@ -185,3 +185,26 @@ def test_suggestions_always_give_the_number_of_bands_asked_for(method, bands): data = np.random.default_rng(1).normal(22, 3, 300) assert len(colour_scales.thresholds(data, bands, method)) == bands - 1 assert len(colour_scales.thresholds([16, 30], bands, "nice")) == bands - 1 + + +def test_clean_data_handles_numeric_and_mixed_input(): + from python_toolkit.plot.colour_scales import clean_data + + assert clean_data(np.array([[1, 2], [3, np.nan]])).tolist() == [1.0, 2.0, 3.0] + assert clean_data([1, None, "x", float("inf"), "4"]).tolist() == [1.0, 4.0] + assert clean_data(v for v in (1, 2)).tolist() == [1.0, 2.0] + + +def test_save_scale_replaces_the_scale_it_edits_even_when_renamed(tmp_path): + from python_toolkit.plot.colour_scales import ColourScaleError, delete_scale + + path = tmp_path / "scales.json" + save_scale(ColourScale("A", [1, 2], "viridis"), path) + save_scale(ColourScale("B", [1, 2], "viridis"), path) + save_scale(ColourScale("C", [5, 6], "viridis"), path, replaces="A") # A renamed to C + assert sorted(s.name for s in load_scales(path)) == ["B", "C"] + with pytest.raises(ColourScaleError): # renaming onto another saved scale is still refused + save_scale(ColourScale("B", [5, 6], "viridis"), path, replaces="C") + save_scale(ColourScale("B", [5, 6], "viridis"), path, replaces="B") # same name: a plain edit + assert delete_scale("B", path) and not delete_scale("B", path) + assert [s.name for s in load_scales(path)] == ["C"] From a4d89ee99c23ef976f1197dbd70971a4ff84d461 Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Wed, 11 Nov 2026 11:40:57 +0000 Subject: [PATCH 5/8] refactored code structure --- .../bhom_tkinter/widgets/cmap_selector.py | 41 +- .../windows/colour_scale_builder.py | 471 ++++++++++-------- .../python_toolkit/colour_scales/__init__.py | 26 + .../python_toolkit/colour_scales/breaks.py | 122 +++++ .../colour_scales/colour_scale.py | 179 +++++++ .../python_toolkit/colour_scales/errors.py | 5 + .../src/python_toolkit/colour_scales/jenks.py | 68 +++ .../python_toolkit/colour_scales/library.py | 97 ++++ .../python_toolkit/colour_scales/values.py | 32 ++ .../src/python_toolkit/palettes/__init__.py | 30 ++ .../src/python_toolkit/palettes/palette.py | 32 ++ .../src/python_toolkit/palettes/registry.py | 92 ++++ .../palettes/toolkit_palettes.py | 28 ++ .../plot/colour_scale_histogram.py | 44 ++ .../src/python_toolkit/plot/colour_scales.py | 324 ------------ .../src/python_toolkit/plot/palettes.py | 69 --- .../Python/tests/test_colour_scale_builder.py | 66 +-- .../Python/tests/test_colour_scales.py | 83 +-- 18 files changed, 1116 insertions(+), 693 deletions(-) create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/__init__.py create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/breaks.py create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/colour_scale.py create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/errors.py create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/jenks.py create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/library.py create mode 100644 Python_Engine/Python/src/python_toolkit/colour_scales/values.py create mode 100644 Python_Engine/Python/src/python_toolkit/palettes/__init__.py create mode 100644 Python_Engine/Python/src/python_toolkit/palettes/palette.py create mode 100644 Python_Engine/Python/src/python_toolkit/palettes/registry.py create mode 100644 Python_Engine/Python/src/python_toolkit/palettes/toolkit_palettes.py create mode 100644 Python_Engine/Python/src/python_toolkit/plot/colour_scale_histogram.py delete mode 100644 Python_Engine/Python/src/python_toolkit/plot/colour_scales.py delete mode 100644 Python_Engine/Python/src/python_toolkit/plot/palettes.py diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index c073ce0..3cce604 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py @@ -10,8 +10,8 @@ from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget from python_toolkit.bhom_tkinter.widgets._packing_options import PackingOptions -from python_toolkit.plot import palettes -from python_toolkit.plot.colour_scales import ColourScale, ColourScaleError, clean_data, delete_scale, load_scales +from python_toolkit.palettes import PaletteGroup, palette_names +from python_toolkit.colour_scales import ColourScale, ColourScaleError, delete_scale, finite_values, load_scales from python_toolkit.bhom.analytics import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.theming.scaling import scale_pad @@ -56,7 +56,7 @@ def __init__( `cmap_set` selection is ignored. cmap_set: Preset colormap set used when `colormaps` is `None`. Allowed values: "all", "continuous", "categorical", "colourblind" - (see `python_toolkit.plot.palettes`). + (see `python_toolkit.palettes.PaletteGroup`). cmap_bins: Number of discrete gradient bands in the preview swatch. default_cmap: Optional default colormap to pre-select. Accepts the same input types as items in `colormaps`. @@ -64,7 +64,7 @@ def __init__( dropdown_position: Position of the dropdown relative to the preview swatch. "n" = above, "s" = below, "w" = left, "e" = right. - include_scales: List the saved colour scales (see `python_toolkit.plot.colour_scales`) + include_scales: List the saved colour scales (see `python_toolkit.colour_scales`) as "Name (scale)" entries, with buttons to build, edit and delete them. Use `get_scale()` and `get_norm()` to colour data with the selected scale. data: Values the scales will colour; passed to the scale builder for its @@ -78,7 +78,7 @@ def __init__( self.cmap_bins = cmap_bins self.plot_size = plot_size self.include_scales = include_scales - self.data = None if data is None else clean_data(data) + self.data = None if data is None else finite_values(data) self.units = units self.scales_path = scales_path self._scales: Dict[str, ColourScale] = {} # combobox label -> saved scale @@ -91,7 +91,7 @@ def __init__( self.cmap_frame.pack(side="top", fill="both", expand=True, anchor=self._pack_anchor) self.colormap_var = tk.StringVar(value="viridis") - self._all_colormaps = palettes.names() + self._all_colormaps = palette_names() self._uses_explicit_colormaps = colormaps is not None self.cmap_frame.columnconfigure(0, weight=1) @@ -182,7 +182,8 @@ def _preset_colormaps(self, cmap_set: str) -> List[str]: List[str]: Colormap names for the requested preset. """ key = (cmap_set or "all").lower() - return self._with_reversed(palettes.names(key if key in palettes.KINDS else None)) + group = key if key in {g.value for g in PaletteGroup} else None # "all", or anything unknown, lists every map + return self._with_reversed(palette_names(group)) def _resolve_colormaps(self, colormaps: List[CmapInput]) -> tuple[List[str], Dict[str, Colormap]]: """Normalise a mixed list of colormap inputs into display labels and a custom-cmap registry. @@ -359,9 +360,11 @@ def get_cmap(self) -> Optional[Colormap]: @staticmethod def _scale_label(name: str) -> str: + """The dropdown label of a saved scale, which sets it apart from palettes of the same name.""" return f"{name} (scale)" def _build_scale_buttons(self, parent: ttk.Frame) -> None: + """Add the New / Edit / Delete scale buttons below the dropdown.""" row = ttk.Frame(parent) row.pack(side=tk.TOP, anchor=self._pack_anchor, pady=(4, 0)) self.new_scale_button = ttk.Button(row, text="New scale…", command=lambda: self._open_builder(None)) @@ -372,6 +375,7 @@ def _build_scale_buttons(self, parent: ttk.Frame) -> None: self._update_scale_buttons() def _update_scale_buttons(self) -> None: + """Enable Edit and Delete only while a saved scale is selected.""" state = ["!disabled"] if self.get_scale() is not None else ["disabled"] self.edit_scale_button.state(state) self.delete_scale_button.state(state) @@ -389,7 +393,7 @@ def _refresh_scales(self, select: Optional[str] = None) -> None: palette_values = [v for v in self.cmap_combobox["values"] if v not in self._scales] self._scales = {self._scale_label(s.name): s for s in scales} for label, scale in self._scales.items(): - self._custom_cmaps[label] = scale.mapping(self.data)[0] + self._custom_cmaps[label] = scale.cmap_and_norm(self.data)[0] self._populate_cmap_list(palette_values + list(self._scales)) target = self._scale_label(select) if select else previous if target in self.cmap_combobox["values"]: @@ -407,19 +411,22 @@ def _open_builder(self, scale: Optional[ColourScale]) -> None: current = self.colormap_var.get() builder = ColourScaleBuilder( self.winfo_toplevel(), data=self.data, units=self.units, scale=scale, library_path=self.scales_path, - palette=current if current in palettes.names() else None, on_save=self._on_scale_saved) + palette=current if current in self._all_colormaps else None, on_save=self._on_scale_saved) builder.run() def _on_scale_saved(self, scale: ColourScale) -> None: + """Reload the saved scales and select the one just saved.""" self._refresh_scales(select=scale.name) self._fire_on_change(self.get()) def _edit_scale(self) -> None: + """Open the builder on the selected scale.""" scale = self.get_scale() if scale is not None: self._open_builder(scale) def _delete_scale(self) -> None: + """Delete the selected scale from the saved scales file, after the user confirms.""" scale = self.get_scale() if scale is None or not messagebox.askyesno("Delete colour scale", f"Delete the saved scale '{scale.name}'?"): return @@ -432,15 +439,23 @@ def _delete_scale(self) -> None: self._fire_on_change(self.get()) def get_scale(self) -> Optional[ColourScale]: - """The selected saved colour scale, or None when a plain palette is selected.""" + """Return the selected saved colour scale. + + Returns: + Optional[ColourScale]: The scale, or None when a plain palette is selected. + """ return self._scales.get(self.colormap_var.get()) def get_norm(self) -> Optional[BoundaryNorm]: - """The normaliser for the selected scale (thresholds in data units), or None for a plain palette. + """Return the normaliser for the selected scale, with its thresholds in data units. - Colour data with `get_cmap()` and `get_norm()` together; the end bands run to the `data` given.""" + Colour data with `get_cmap()` and `get_norm()` together; the end bands run to the `data` given. + + Returns: + Optional[BoundaryNorm]: The normaliser, or None when a plain palette is selected. + """ scale = self.get_scale() - return scale.mapping(self.data)[1] if scale is not None else None + return scale.cmap_and_norm(self.data)[1] if scale is not None else None def add_cmap(self, cmap: CmapInput, label: Optional[str] = None) -> Optional[str]: """Dynamically add a new colormap entry to the selector. diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py index 9fb0a99..758f238 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -2,27 +2,25 @@ Pass the data in and the window shows its distribution, suggests band thresholds, and lets the user colour, label and save the scale to the saved scales file -(``python_toolkit.plot.colour_scales``):: +(see ``python_toolkit.colour_scales``):: builder = ColourScaleBuilder(parent, data=room_temperatures, units="degC") builder.run() scale = builder.saved_scale # None if closed without saving """ -from __future__ import annotations - import math import tkinter as tk -from tkinter import ttk +from dataclasses import dataclass from pathlib import Path -from typing import Callable, Iterable, List, Optional +from tkinter import ttk +from typing import Callable, Iterable, Optional, Sequence import numpy as np -from matplotlib.figure import Figure from python_toolkit.bhom.logging import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.bhom_base_child_window import BHoMBaseChildWindow -from python_toolkit.bhom_tkinter.windows.warning_box import WarningBox +from python_toolkit.bhom_tkinter.theming.scaling import scale as scale_px from python_toolkit.bhom_tkinter.widgets._grid_options import GridOptions from python_toolkit.bhom_tkinter.widgets.colour_picker import ColourPicker from python_toolkit.bhom_tkinter.widgets.drop_down_selection import DropDownSelection @@ -30,37 +28,37 @@ from python_toolkit.bhom_tkinter.widgets.label import Label from python_toolkit.bhom_tkinter.widgets.spinbox import Spinbox from python_toolkit.bhom_tkinter.widgets.validated_entry_box import ValidatedEntryBox -from python_toolkit.bhom_tkinter.theming.scaling import scale as scale_px -from python_toolkit.plot import colour_scales, palettes -from python_toolkit.plot.colour_scales import ( - SUGGESTION_METHODS, +from python_toolkit.bhom_tkinter.windows.warning_box import WarningBox +from python_toolkit.colour_scales import ( + BreakMethod, ColourScale, ColourScaleError, - clean_data, + finite_values, load_scales, save_scale, + suggest_thresholds, ) +from python_toolkit.palettes import palette_names, sample_colours +from python_toolkit.plot.colour_scale_histogram import colour_scale_histogram MAX_BANDS = 24 TYPING_DELAY = 700 # ms to wait after the last keystroke, so "22" is not read as "2" first PLOT_WIDTH = 560 # the plot, the controls and the band table all share this width ERROR_COLOUR = "#c0392b" - -def _spin_step(span: float) -> float: - """A round step (1, 2 or 5 x 10^n) of about a hundredth of the span, for spinning a threshold.""" - raw = span / 100 if span > 0 else 0.01 - power = 10 ** math.floor(math.log10(raw)) - return next(factor * power for factor in (5, 2, 1) if factor * power <= raw) +Bands = tuple[list[float], list[str], list[Optional[str]]] # thresholds, colours, labels -def _plain(box: ValidatedEntryBox) -> ValidatedEntryBox: - """Drop the tick and the message line an entry box reserves, so its edges line up with its neighbours. +@dataclass +class BandRow: + """The widgets of one row of the band table.""" - Problems are reported in the window's status line instead.""" - box.success_label.pack_forget() - box.error_label.pack_forget() - return box + colour: ColourPicker + label: ValidatedEntryBox + lower: ttk.Label + upper: Optional[Spinbox] # None for the last, open-ended band + split: ttk.Button + remove: ttk.Button class ColourScaleBuilder(BHoMBaseChildWindow): @@ -68,7 +66,7 @@ class ColourScaleBuilder(BHoMBaseChildWindow): def __init__( self, - parent=None, + parent: Optional[tk.Misc] = None, data: Optional[Iterable] = None, units: Optional[str] = None, scale: Optional[ColourScale] = None, @@ -76,7 +74,7 @@ def __init__( on_save: Optional[Callable[[ColourScale], None]] = None, palette: Optional[str] = None, **kwargs, - ): + ) -> None: """ Args: parent: Owning window (None for a standalone window). @@ -85,18 +83,19 @@ def __init__( scale: An existing scale to edit (saving replaces it). library_path: File to save into (defaults to the user's saved scales). on_save: Called with the saved scale. - palette: Palette or matplotlib colour map to start from (e.g. the plot's current one). + palette: Palette to start from (e.g. the plot's current one). + **kwargs: Additional BHoMBaseChildWindow options. """ - self.values = clean_data(data) + self.values = finite_values(data) self.units = units if units is not None else (scale.units if scale else None) self.library_path = library_path self.editing = scale self.on_save = on_save self.saved_scale: Optional[ColourScale] = None - self._band_rows: List[dict] = [] - self._pending = None + self._band_rows: list[BandRow] = [] + self._preview_job: Optional[str] = None + self._suggest_job: Optional[str] = None self._syncing = False - self._suggest_job = None self._start_palette = palette super().__init__( parent, @@ -121,31 +120,41 @@ def __init__( # ── layout ───────────────────────────────────────────────────────────── def _build_contents(self) -> None: + """Lay out the name, data summary, preview, status line, controls and band table.""" frame = self.content_frame frame.columnconfigure(0, weight=1) left = dict(column=0, sticky="ew", padx=0) - self.name = _plain(ValidatedEntryBox( + self.name = _without_message_line(ValidatedEntryBox( frame, id="name", helper_text="Name", required=False, width=30, on_change=lambda _v: self._schedule_preview(TYPING_DELAY), # re-checks, clearing old errors build_options=GridOptions(row=0, pady=3, **left))) - self.data_text = Label(frame, text=self._summary_text(), build_options=GridOptions(row=2, **left)) + self.data_text = Label(frame, text=self._data_summary(), build_options=GridOptions(row=2, **left)) self.preview = FigureContainer(frame, id="preview", rigid_width=PLOT_WIDTH, rigid_height=130, build_options=GridOptions(row=3, pady=4, **left)) self.status = Label(frame, text="", foreground=ERROR_COLOUR, wraplength=scale_px(PLOT_WIDTH), justify="left", build_options=GridOptions(row=4, **left)) + self._build_controls(frame, row=5) + + self.bands_frame = ttk.Frame(frame) + self.bands_frame.grid(row=6, pady=3, **left) + self.bands_frame.columnconfigure(1, weight=1) # the label box takes the spare width + self.widgets = [self.name, self.data_text, self.preview, self.status] - controls = ttk.Frame(frame) - controls.grid(row=5, pady=3, **left) + def _build_controls(self, parent: ttk.Frame, row: int) -> None: + """Lay out the band count, break method and palette controls in one row.""" + controls = ttk.Frame(parent) + controls.grid(row=row, column=0, sticky="ew", padx=0, pady=3) controls.columnconfigure(2, weight=1) # the palette takes the spare width self.band_count = Spinbox(controls, id="bands", helper_text="Bands", values=list(range(2, MAX_BANDS + 1)), - default=5, width=4, command=lambda _v: self._auto_suggest(TYPING_DELAY), + default=5, width=4, command=lambda _v: self._schedule_suggestion(TYPING_DELAY), build_options=GridOptions(row=0, column=0, sticky="w", padx=(0, 8))) - self.method = DropDownSelection(controls, id="method", helper_text="Breaks", options=list(SUGGESTION_METHODS), - default="nice", state="readonly", width=7, - command=lambda _v: self._auto_suggest(0), + self.method = DropDownSelection(controls, id="method", helper_text="Breaks", + options=[method.value for method in BreakMethod], + default=BreakMethod.NICE.value, state="readonly", width=7, + command=lambda _v: self._schedule_suggestion(0), build_options=GridOptions(row=0, column=1, sticky="w", padx=(0, 8))) - options = palettes.names() + options = palette_names() self.palette = DropDownSelection(controls, id="palette", helper_text="Palette / colour map", options=options, default=self._start_palette if self._start_palette in options else "viridis", state="readonly", width=6, command=lambda _v: self._recolour(), @@ -156,44 +165,42 @@ def _build_contents(self) -> None: self.band_count.spinbox.configure(state="disabled") self.method.combobox.configure(state="disabled") - self.bands_frame = ttk.Frame(frame) - self.bands_frame.grid(row=6, pady=3, **left) - self.bands_frame.columnconfigure(1, weight=1) # the label box takes the spare width - self.widgets = [self.name, self.data_text, self.preview, self.status] - - def _summary_text(self) -> str: + def _data_summary(self) -> str: + """One line describing the data: count, range, median and middle half.""" if not self.values.size: return "No data passed in: set the thresholds by hand." - q1, q2, q3 = np.quantile(self.values, [0.25, 0.5, 0.75]) + q1, median, q3 = np.quantile(self.values, [0.25, 0.5, 0.75]) units = f" {self.units}" if self.units else "" return (f"{self.values.size} values from {self.values.min():.4g} to {self.values.max():.4g}{units}; " - f"median {q2:.4g}, middle half {q1:.4g} to {q3:.4g}") + f"median {median:.4g}, middle half {q1:.4g} to {q3:.4g}") # ── state ────────────────────────────────────────────────────────────── def _load(self, scale: Optional[ColourScale]) -> None: + """Fill the window from the scale being edited, or start a new one.""" if scale is not None: self.name.set(scale.name) if isinstance(scale.cmap, str): self.palette.set(scale.cmap) - self._set_bands(scale.thresholds, scale.colours(), scale.labels) - elif self.values.size: - self.name.set(self._unused_name("New scale")) - self._suggest() + self._show_bands(scale.thresholds, scale.colours(), scale.labels) else: self.name.set(self._unused_name("New scale")) - self._set_bands([1.0, 2.0], palettes.sample(self.palette.get(), 3), None) + if self.values.size: + self._suggest() + else: + self._show_bands([1.0, 2.0], sample_colours(self.palette.get(), 3), None) self._schedule_preview() - def _auto_suggest(self, delay: int) -> None: - """Re-suggest the bands once the band count or break method has settled.""" + def _schedule_suggestion(self, delay: int) -> None: + """Re-suggest the bands once the band count or break method has settled for `delay` ms.""" if self._syncing or not self.values.size: return if self._suggest_job is not None: self.after_cancel(self._suggest_job) - self._suggest_job = self.after(delay, self._run_auto_suggest) + self._suggest_job = self.after(delay, self._run_scheduled_suggestion) - def _run_auto_suggest(self) -> None: + def _run_scheduled_suggestion(self) -> None: + """Suggest the bands, if the band count box holds a valid count.""" self._suggest_job = None try: bands = int(self.band_count.get()) @@ -203,184 +210,208 @@ def _run_auto_suggest(self) -> None: self._suggest() def _suggest(self) -> None: + """Replace the thresholds with suggested ones, keeping hand-picked colours and labels where bands remain.""" try: - bands = int(self.band_count.get()) - thresholds = colour_scales.thresholds(self.values, bands, self.method.get()) - except (ColourScaleError, ValueError) as e: - self.status.set(str(e)) + thresholds = suggest_thresholds(self.values, int(self.band_count.get()), self.method.get()) + except (ColourScaleError, ValueError) as error: + self.status.set(str(error)) return - n = len(thresholds) + 1 - palette = self.palette.get() - old_colours = [row["colour"].get() for row in self._band_rows] - old_labels = [(row["label"].get() or "").strip() or None for row in self._band_rows] - fresh = palettes.sample(palette, n) - # keep hand-picked colours and any labels on the bands that remain; new breaks only replace the thresholds - customised = bool(old_colours) and old_colours != palettes.sample(palette, len(old_colours)) - colours = [old_colours[i] if customised and i < len(old_colours) else fresh[i] for i in range(n)] - labels = (old_labels + [None] * n)[:n] - self._set_bands(thresholds, colours, labels if any(labels) else None) + count = len(thresholds) + 1 + old_colours = [row.colour.get() for row in self._band_rows] + old_labels = [(row.label.get() or "").strip() or None for row in self._band_rows] + palette_colours = sample_colours(self.palette.get(), count) + if old_colours and self._is_hand_coloured(old_colours): + colours = [old_colours[i] if i < len(old_colours) else palette_colours[i] for i in range(count)] + else: + colours = palette_colours + labels = (old_labels + [None] * count)[:count] + self._show_bands(thresholds, colours, labels) def _split_band(self, index: int) -> None: - """Add a band by splitting this one in two at the middle of its range; the new band starts empty.""" + """Add a band by splitting band `index` in two at the middle of its range; the new band starts unlabelled.""" try: thresholds, colours, labels = self._read_bands() - except ColourScaleError as e: - self.status.set(str(e)) + except ColourScaleError as error: + self.status.set(str(error)) return - n = len(colours) - if n >= MAX_BANDS: + if len(colours) >= MAX_BANDS: return - typical = float(np.mean(np.diff(thresholds))) if len(thresholds) > 1 else 0.0 - if not typical and self.values.size: - typical = float(self.values.max() - self.values.min()) / n - typical = typical or 1.0 - lower = thresholds[index - 1] if index > 0 else None - upper = thresholds[index] if index < n - 1 else None - data_lo = float(self.values.min()) if self.values.size else None - data_hi = float(self.values.max()) if self.values.size else None - # an open end is split against the data's extreme, or one typical band width beyond the last threshold - lo = lower if lower is not None else (data_lo if data_lo is not None and data_lo < upper else upper - typical) - hi = upper if upper is not None else (data_hi if data_hi is not None and data_hi > lower else lower + typical) - new = float(f"{(lo + hi) / 2:.6g}") - if not lo < new < hi: + low, high = self._band_extent(index, thresholds) + middle = float(f"{(low + high) / 2:.6g}") + if not low < middle < high: self.status.set("There is no room to split this band; move its thresholds apart first.") return - was_customised = colours != palettes.sample(self.palette.get(), n) - thresholds.insert(index, new) + hand_coloured = self._is_hand_coloured(colours) + thresholds.insert(index, middle) colours.insert(index + 1, colours[index]) labels.insert(index + 1, None) - self._rebuild(thresholds, colours, labels, was_customised) + self._show_edited_bands(thresholds, colours, labels, hand_coloured) + + def _band_extent(self, index: int, thresholds: Sequence[float]) -> tuple[float, float]: + """The range of band `index`; an open end band runs to the data's extreme, or one typical band width.""" + count = len(thresholds) + 1 + typical = float(np.mean(np.diff(thresholds))) if len(thresholds) > 1 else 0.0 + if not typical and self.values.size: + typical = float(self.values.max() - self.values.min()) / count + typical = typical or 1.0 + lower = thresholds[index - 1] if index > 0 else None + upper = thresholds[index] if index < count - 1 else None + if lower is None: + data_min = float(self.values.min()) if self.values.size else None + lower = data_min if data_min is not None and data_min < upper else upper - typical + if upper is None: + data_max = float(self.values.max()) if self.values.size else None + upper = data_max if data_max is not None and data_max > lower else lower + typical + return lower, upper def _remove_band(self, index: int) -> None: - """Remove a band; its range joins the band after it (before it, for the last band).""" + """Remove band `index`; its range joins the band after it (before it, for the last band).""" try: thresholds, colours, labels = self._read_bands() - except ColourScaleError as e: - self.status.set(str(e)) + except ColourScaleError as error: + self.status.set(str(error)) return - n = len(colours) - if n <= 2: + count = len(colours) + if count <= 2: return - was_customised = colours != palettes.sample(self.palette.get(), n) - thresholds.pop(index if index < n - 1 else n - 2) + hand_coloured = self._is_hand_coloured(colours) + thresholds.pop(min(index, count - 2)) colours.pop(index) labels.pop(index) - self._rebuild(thresholds, colours, labels, was_customised) + self._show_edited_bands(thresholds, colours, labels, hand_coloured) - def _rebuild(self, thresholds, colours, labels, was_customised: bool) -> None: - """Show an edited table: hand-picked colours stay, otherwise the palette is spread over the new bands.""" - if not was_customised: - colours = palettes.sample(self.palette.get(), len(colours)) - self._set_bands(thresholds, colours, labels if any(labels) else None) + def _show_edited_bands(self, thresholds: list[float], colours: list[str], labels: list[Optional[str]], + hand_coloured: bool) -> None: + """Show an edited band table: hand-picked colours stay, otherwise the palette is spread over the new bands.""" + if not hand_coloured: + colours = sample_colours(self.palette.get(), len(colours)) + self._show_bands(thresholds, colours, labels) + + def _is_hand_coloured(self, colours: list[str]) -> bool: + """Whether the band colours differ from the selected palette's, i.e. were picked by hand.""" + return colours != sample_colours(self.palette.get(), len(colours)) def _recolour(self) -> None: - """A new palette recolours the bands, keeping their thresholds and labels.""" + """Recolour the bands from the newly selected palette, keeping their thresholds and labels.""" if not self._band_rows: return - for row, colour in zip(self._band_rows, palettes.sample(self.palette.get(), len(self._band_rows))): - row["colour"].set(colour) + for row, colour in zip(self._band_rows, sample_colours(self.palette.get(), len(self._band_rows))): + row.colour.set(colour) self._schedule_preview() - def _set_bands(self, thresholds, colours, labels) -> None: + def _show_bands(self, thresholds: Sequence[float], colours: Sequence[str], + labels: Optional[Sequence[Optional[str]]]) -> None: + """Rebuild the band table with one row per colour.""" for child in self.bands_frame.winfo_children(): child.destroy() - self._band_rows = [] - n = len(colours) - # thresholds are spin boxes: step about 1% of the data range, anywhere from one range below to one above - lo = min([*thresholds, *([self.values.min()] if self.values.size else [])]) - hi = max([*thresholds, *([self.values.max()] if self.values.size else [])]) - span = (hi - lo) or 1.0 - step = _spin_step(span) - headers = ("Colour", "Label (legend)", "From", "Up to", "") - for col, text in enumerate(headers): - ttk.Label(self.bands_frame, text=text, style="Caption.TLabel").grid(row=0, column=col, sticky="w", padx=(0, 8)) - for i in range(n): - picker = ColourPicker(self.bands_frame, default_colour=colours[i], swatch_width=36, swatch_height=20, - command=lambda _c: self._schedule_preview()) - picker.grid(row=i + 1, column=0, sticky="w", padx=(0, 8)) - label = _plain(ValidatedEntryBox(self.bands_frame, required=False, width=10, - on_change=lambda _v: self._schedule_preview(TYPING_DELAY))) - label.grid(row=i + 1, column=1, sticky="ew", padx=(0, 8)) - label.set((labels[i] or "") if labels else "") - lower = ttk.Label(self.bands_frame, text="") - lower.grid(row=i + 1, column=2, sticky="w", padx=(0, 8)) - upper = None - if i < n - 1: - upper = Spinbox(self.bands_frame, from_=lo - span, to=hi + span, increment=step, width=10, - command=lambda _v: self._schedule_preview(TYPING_DELAY)) - upper.spinbox.configure(format="%.6g") # no float noise while spinning - upper.grid(row=i + 1, column=3, sticky="w") - upper.set(f"{thresholds[i]:.6g}") - else: - ttk.Label(self.bands_frame, text="and above").grid(row=i + 1, column=3, sticky="w") - actions = ttk.Frame(self.bands_frame) - actions.grid(row=i + 1, column=4, sticky="e", padx=(8, 0)) - split = ttk.Button(actions, text="Split", width=6, command=lambda i=i: self._split_band(i)) - remove = ttk.Button(actions, text="Remove", width=7, command=lambda i=i: self._remove_band(i)) - split.pack(side="left", padx=(0, 4)) - remove.pack(side="left") - if n >= MAX_BANDS: - split.state(["disabled"]) - if n <= 2: - remove.state(["disabled"]) - self._band_rows.append({"colour": picker, "label": label, "lower": lower, "upper": upper, - "split": split, "remove": remove}) + for column, text in enumerate(("Colour", "Label (legend)", "From", "Up to", "")): + ttk.Label(self.bands_frame, text=text, style="Caption.TLabel").grid(row=0, column=column, sticky="w", + padx=(0, 8)) + labels = labels or [None] * len(colours) + self._band_rows = [self._add_band_row(i, thresholds, colours[i], labels[i]) for i in range(len(colours))] self._syncing = True # showing the count must not re-suggest the bands - self.band_count.set(n) + self.band_count.set(len(colours)) self._syncing = False self._schedule_preview() if self._has_been_shown: # the window follows the number of band rows self.update_idletasks() self._apply_sizing() - def _read_bands(self): - """The table as (thresholds, colours, labels); raises ColourScaleError for a threshold that is not a number.""" + def _add_band_row(self, index: int, thresholds: Sequence[float], colour: str, label: Optional[str]) -> BandRow: + """Add the widgets for band `index` to the band table.""" + row = index + 1 # below the header + count = len(thresholds) + 1 + picker = ColourPicker(self.bands_frame, default_colour=colour, swatch_width=36, swatch_height=20, + command=lambda _c: self._schedule_preview()) + picker.grid(row=row, column=0, sticky="w", padx=(0, 8)) + label_box = _without_message_line(ValidatedEntryBox( + self.bands_frame, required=False, width=10, on_change=lambda _v: self._schedule_preview(TYPING_DELAY))) + label_box.grid(row=row, column=1, sticky="ew", padx=(0, 8)) + label_box.set(label or "") + lower = ttk.Label(self.bands_frame, text="") + lower.grid(row=row, column=2, sticky="w", padx=(0, 8)) + upper = self._threshold_spinbox(thresholds, index) if index < count - 1 else None + if upper is not None: + upper.grid(row=row, column=3, sticky="w") + else: + ttk.Label(self.bands_frame, text="and above").grid(row=row, column=3, sticky="w") + actions = ttk.Frame(self.bands_frame) + actions.grid(row=row, column=4, sticky="e", padx=(8, 0)) + split = ttk.Button(actions, text="Split", width=6, command=lambda: self._split_band(index)) + remove = ttk.Button(actions, text="Remove", width=7, command=lambda: self._remove_band(index)) + split.pack(side="left", padx=(0, 4)) + remove.pack(side="left") + if count >= MAX_BANDS: + split.state(["disabled"]) + if count <= 2: + remove.state(["disabled"]) + return BandRow(picker, label_box, lower, upper, split, remove) + + def _threshold_spinbox(self, thresholds: Sequence[float], index: int) -> Spinbox: + """A spin box for threshold `index`, stepping about 1% of the data range, within one range either side.""" + known = [*thresholds, *([self.values.min(), self.values.max()] if self.values.size else [])] + low, high = min(known), max(known) + span = (high - low) or 1.0 + spinbox = Spinbox(self.bands_frame, from_=low - span, to=high + span, increment=_round_step(span), width=10, + command=lambda _v: self._schedule_preview(TYPING_DELAY)) + spinbox.spinbox.configure(format="%.6g") # no float noise while spinning + spinbox.set(f"{thresholds[index]:.6g}") + return spinbox + + def _read_bands(self) -> Bands: + """Read the band table. + + Returns: + Bands: The thresholds, colours and labels (None where blank). + + Raises: + ColourScaleError: If a threshold is not a number. + """ thresholds = [] for i, row in enumerate(self._band_rows[:-1]): - text = str(row["upper"].get()).strip() + text = str(row.upper.get()).strip() try: thresholds.append(float(text)) except ValueError: raise ColourScaleError(f"Band {i + 1}: '{text}' is not a number.") from None - colours = [row["colour"].get() for row in self._band_rows] - labels = [(row["label"].get() or "").strip() or None for row in self._band_rows] + colours = [row.colour.get() for row in self._band_rows] + labels = [(row.label.get() or "").strip() or None for row in self._band_rows] return thresholds, colours, labels def current_scale(self) -> ColourScale: - """The scale described by the window right now (raises ColourScaleError if invalid).""" - name = (self.name.get() or "").strip() - palette = self.palette.get() + """The scale the window describes right now. + + Returns: + ColourScale: The scale. Its colours are the palette name unless a band colour was picked by hand. + + Raises: + ColourScaleError: If the name, thresholds or colours are invalid. + """ thresholds, colours, labels = self._read_bands() - # keep the palette as the scale's colours unless a band colour was changed by hand - cmap = palette if colours == palettes.sample(palette, len(colours)) else colours - return ColourScale(name, thresholds, cmap, labels if any(labels) else None, self.units) + cmap = colours if self._is_hand_coloured(colours) else self.palette.get() + return ColourScale((self.name.get() or "").strip(), thresholds, cmap, labels if any(labels) else None, + self.units) def _unused_name(self, base: str) -> str: + """`base`, or `base 2`, `base 3`... whichever is not yet a saved scale's name.""" try: - names = {s.name for s in load_scales(self.library_path)} - except ColourScaleError as e: # an unreadable library must not stop the window opening; saving reports it - CONSOLE_LOGGER.warning(str(e)) - names = set() - n = 1 - name = base - while name in names: - n += 1 - name = f"{base} {n}" + taken = {scale.name for scale in load_scales(self.library_path)} + except ColourScaleError as error: # an unreadable library must not stop the window opening; saving reports it + CONSOLE_LOGGER.warning(str(error)) + taken = set() + name, number = base, 1 + while name in taken: + number += 1 + name = f"{base} {number}" return name def _save(self) -> None: - """Validate, save to the library and close; errors are shown in a pop-up and stay in the window.""" + """Save the scale to the library and close; errors are shown in a pop-up and the window stays open.""" try: scale = self.current_scale() save_scale(scale, self.library_path, replaces=self.editing.name if self.editing else None) - except (ColourScaleError, OSError) as e: - message = str(e) - if "already exists" in message: - message += " Give this scale another name, or edit the saved one instead." - self.status.set(message) - box = WarningBox(title="Scale not saved", errors=[message], parent=self) - box.build() - box.run() + except (ColourScaleError, OSError) as error: + self._show_save_error(str(error)) return CONSOLE_LOGGER.info(f"Saved colour scale '{scale.name}'.") self.saved_scale = scale @@ -388,60 +419,58 @@ def _save(self) -> None: self.on_save(scale) self.destroy_root() + def _show_save_error(self, message: str) -> None: + """Show why the scale was not saved, in the status line and a pop-up.""" + if "already exists" in message: + message += " Give this scale another name, or edit the saved one instead." + self.status.set(message) + box = WarningBox(title="Scale not saved", errors=[message], parent=self) + box.build() + box.run() + # ── preview ──────────────────────────────────────────────────────────── def _schedule_preview(self, delay: int = 250) -> None: - if self._pending is not None: + """Redraw the preview once the window has been left unchanged for `delay` ms.""" + if self._preview_job is not None: try: - self.after_cancel(self._pending) + self.after_cancel(self._preview_job) except tk.TclError: pass - self._pending = self.after(delay, self._update_preview) + self._preview_job = self.after(delay, self._update_preview) def _update_preview(self) -> None: - self._pending = None + """Redraw the histogram and the band 'From' column, or report why the scale is invalid.""" + self._preview_job = None try: scale = self.current_scale() - except ColourScaleError as e: - self.status.set(str(e)) + except ColourScaleError as error: + self.status.set(str(error)) return self.status.set("") - for row, lower in zip(self._band_rows, [None] + scale.thresholds): - row["lower"].configure(text="below" if lower is None else f"{lower:.6g}") + for row, lower in zip(self._band_rows, [None, *scale.thresholds]): + row.lower.configure(text="below" if lower is None else f"{lower:.6g}") style = ttk.Style() - self.preview.embed_figure(preview_figure(scale, self.values, - background=style.lookup("TFrame", "background") or "#ffffff", - foreground=style.lookup("TLabel", "foreground") or "#000000")) - - -def preview_figure(scale: ColourScale, values: np.ndarray, background: str = "#ffffff", - foreground: str = "#000000") -> Figure: - """Histogram of the data over the scale's colours (or the colours alone without data). - - `background` and `foreground` are the window's colours, so the plot sits in light or dark mode. - """ - fig = Figure(figsize=(5.6, 1.3), dpi=100, facecolor=background) - ax = fig.add_axes([0.0, 0.2, 1.0, 0.76], facecolor=background) - cmap, norm = scale.mapping() - lo, hi = scale.value_range(values) - xs = np.linspace(lo, hi, 400) - ax.imshow(cmap(norm(xs))[np.newaxis, :, :], aspect="auto", extent=(xs[0], xs[-1], 0, 1), alpha=0.85, - origin="lower", zorder=0) - if values.size: - counts, edges = np.histogram(values, bins=30, range=(lo, hi)) - ax.bar(edges[:-1], counts / max(counts.max(), 1), width=np.diff(edges), align="edge", color=foreground, - alpha=0.45, edgecolor=background, linewidth=0.6, zorder=1) - for t in scale.thresholds: - if xs[0] <= t <= xs[-1]: - ax.axvline(t, color=foreground, linewidth=1.2, zorder=2) - ax.set_xlim(xs[0], xs[-1]) - ax.set_ylim(0, 1.05) - ax.set_yticks([]) - ax.tick_params(labelsize=7, colors=foreground) - for side in ("top", "right", "left"): - ax.spines[side].set_visible(False) - ax.spines["bottom"].set_color(foreground) - return fig + self.preview.embed_figure(colour_scale_histogram( + scale, self.values, + background=style.lookup("TFrame", "background") or "#ffffff", + foreground=style.lookup("TLabel", "foreground") or "#000000")) + + +def _round_step(span: float) -> float: + """A round step (1, 2 or 5 x 10^n) of about a hundredth of the span, for spinning a threshold.""" + raw = span / 100 if span > 0 else 0.01 + power = 10 ** math.floor(math.log10(raw)) + return next(factor * power for factor in (5, 2, 1) if factor * power <= raw) + + +def _without_message_line(box: ValidatedEntryBox) -> ValidatedEntryBox: + """Drop the tick and the message line an entry box reserves, so its edges line up with its neighbours. + + Problems are reported in the window's status line instead.""" + box.success_label.pack_forget() + box.error_label.pack_forget() + return box if __name__ == "__main__": diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/__init__.py b/Python_Engine/Python/src/python_toolkit/colour_scales/__init__.py new file mode 100644 index 0000000..80524de --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/__init__.py @@ -0,0 +1,26 @@ +"""Colour scales: data split into bands at thresholds in data units, one colour per band. + + scale = ColourScale("Comfort", thresholds=[18, 21, 24], cmap="coolwarm", units="degC") + cmap, norm = scale.cmap_and_norm(room_temperatures) + save_scale(scale) + + suggest_thresholds(room_temperatures, bands=5, method="jenks") +""" + +from python_toolkit.colour_scales.breaks import BreakMethod, suggest_thresholds +from python_toolkit.colour_scales.colour_scale import ColourScale +from python_toolkit.colour_scales.errors import ColourScaleError +from python_toolkit.colour_scales.library import DEFAULT_LIBRARY_PATH, delete_scale, load_scales, save_scale +from python_toolkit.colour_scales.values import finite_values + +__all__ = [ + "BreakMethod", + "ColourScale", + "ColourScaleError", + "DEFAULT_LIBRARY_PATH", + "delete_scale", + "finite_values", + "load_scales", + "save_scale", + "suggest_thresholds", +] diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/breaks.py b/Python_Engine/Python/src/python_toolkit/colour_scales/breaks.py new file mode 100644 index 0000000..b072ea6 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/breaks.py @@ -0,0 +1,122 @@ +"""Suggesting colour scale thresholds from the data the scale will colour.""" + +import math +from enum import Enum +from typing import Callable, Iterable, Union + +import numpy as np + +from python_toolkit.colour_scales.errors import ColourScaleError +from python_toolkit.colour_scales.jenks import jenks_breaks +from python_toolkit.colour_scales.values import finite_values + + +class BreakMethod(str, Enum): + """Ways of splitting data into bands. + + EQUAL: equal-width bands across the data range. + QUANTILE: roughly the same number of values in each band. + JENKS: natural breaks; the bands that minimise the spread of values within each band. + NICE: equal-width bands on rounded 1 / 2 / 5 x 10^n steps. + LOG: bands of equal ratio, rounded to 3 significant figures; needs every value above zero. + """ + + EQUAL = "equal" + QUANTILE = "quantile" + JENKS = "jenks" + NICE = "nice" + LOG = "log" + + +def suggest_thresholds(data: Iterable, bands: int, method: Union[BreakMethod, str] = BreakMethod.NICE) -> list[float]: + """Suggest the thresholds that split data into bands. + + Args: + data: Values the scale will colour; non-numeric and non-finite values are ignored. + bands: Number of bands wanted, at least 2. + method: How to place the breaks (see BreakMethod). + + Returns: + list[float]: `bands - 1` strictly increasing thresholds. + + Raises: + ColourScaleError: If the arguments are invalid, or the data cannot be split that way. + """ + if bands < 2: + raise ColourScaleError("A threshold scale needs at least 2 bands.") + try: + method = BreakMethod(method) + except ValueError: + options = tuple(m.value for m in BreakMethod) + raise ColourScaleError(f"Method must be one of {options}, not '{method}'.") from None + values = finite_values(data) + if values.size == 0: + raise ColourScaleError("No numeric values to suggest thresholds from.") + low, high = float(values.min()), float(values.max()) + if low == high: + return [low + i for i in range(1, bands)] + return _BREAK_FUNCTIONS[method](values, bands) + + +def _equal_breaks(values: np.ndarray, bands: int) -> list[float]: + """Breaks at equal steps across the data range.""" + return [float(v) for v in np.linspace(values.min(), values.max(), bands + 1)[1:-1]] + + +def _quantile_breaks(values: np.ndarray, bands: int) -> list[float]: + """Breaks that put roughly the same number of values in each band.""" + cuts = sorted({float(c) for c in np.quantile(values, np.linspace(0, 1, bands + 1)[1:-1])}) + if len(cuts) < bands - 1: + raise ColourScaleError("Too many repeated values for that many quantile bands; use fewer bands.") + return cuts + + +def _log_breaks(values: np.ndarray, bands: int) -> list[float]: + """Breaks at equal ratios across the data range, rounded to 3 significant figures.""" + low, high = float(values.min()), float(values.max()) + if low <= 0: + raise ColourScaleError("Logarithmic breaks need every value above zero; use another break method.") + cuts = [float(f"{v:.3g}") for v in np.geomspace(low, high, bands + 1)[1:-1]] + if any(upper <= lower for lower, upper in zip(cuts, cuts[1:])) or cuts[0] <= low or cuts[-1] >= high: + raise ColourScaleError("The data range is too narrow for that many logarithmic bands; use fewer bands.") + return cuts + + +def _nice_breaks(values: np.ndarray, bands: int) -> list[float]: + """Rounded breaks (multiples of 1, 2, 2.5 or 5 x 10^n) strictly inside the data range. + + Picks the step with the fewest breaks that is still enough, then keeps the number wanted, spread + evenly from the first to the last, so every band contains data and the end bands stay small. + Where the step does not divide evenly, some bands are two steps wide. + """ + low, high = float(values.min()), float(values.max()) + wanted = bands - 1 + candidates = _rounded_break_candidates(low, high, wanted) + if not candidates: # range too narrow for rounded breaks + return [float(v) for v in np.linspace(low, high, wanted + 2)[1:-1]] + return [candidates[i] for i in np.linspace(0, len(candidates) - 1, wanted).round().astype(int)] + + +def _rounded_break_candidates(low: float, high: float, wanted: int) -> list[float]: + """Every multiple of the best rounded step strictly between low and high, or [] if no step gives enough.""" + exponent = math.floor(math.log10((high - low) / (wanted + 1))) + best_score, best_breaks = math.inf, [] + for power in (exponent - 1, exponent, exponent + 1): + for factor in (1, 2, 2.5, 5): + step = factor * 10 ** power + breaks = [round(k * step, 10) for k in range(math.floor(low / step) + 1, math.ceil(high / step))] + if len(breaks) < wanted: + continue + score = len(breaks) - wanted + (0.5 if factor == 2.5 else 0.0) # prefer rounder steps + if score < best_score: + best_score, best_breaks = score, breaks + return best_breaks + + +_BREAK_FUNCTIONS: dict[BreakMethod, Callable[[np.ndarray, int], list[float]]] = { + BreakMethod.EQUAL: _equal_breaks, + BreakMethod.QUANTILE: _quantile_breaks, + BreakMethod.JENKS: jenks_breaks, + BreakMethod.NICE: _nice_breaks, + BreakMethod.LOG: _log_breaks, +} diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/colour_scale.py b/Python_Engine/Python/src/python_toolkit/colour_scales/colour_scale.py new file mode 100644 index 0000000..f4de721 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/colour_scale.py @@ -0,0 +1,179 @@ +"""A colour scale: data split into bands at thresholds in data units, one colour per band.""" + +from typing import Any, Iterable, Optional, Sequence, Union + +from matplotlib import colormaps +from matplotlib.colors import BoundaryNorm, ListedColormap, to_hex, to_rgba + +from python_toolkit.colour_scales.errors import ColourScaleError +from python_toolkit.colour_scales.values import finite_values +from python_toolkit.palettes import sample_colours + + +class ColourScale: + """A named set of bands split at thresholds in data units, coloured by a palette or explicit colours. + + A matplotlib Colormap only knows positions from 0 to 1, so a "18 / 21 / 24 degC" band set drifts + whenever the data range changes. A ColourScale keeps its thresholds in data units, so it colours + any data the same way: + + scale = ColourScale("Comfort", thresholds=[18, 21, 24], cmap="coolwarm", + labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") + cmap, norm = scale.cmap_and_norm() + ax.scatter(x, y, c=room_temperatures, cmap=cmap, norm=norm) + """ + + def __init__( + self, + name: str, + thresholds: Sequence[float], + cmap: Union[str, Sequence[str]] = "viridis", + labels: Optional[Sequence[Optional[str]]] = None, + units: Optional[str] = None, + ) -> None: + """ + Args: + name: Name of the scale; must not be blank. + thresholds: Band boundaries in data units, strictly increasing. N thresholds make N + 1 bands. + cmap: A registered palette name, or one colour per band. + labels: One legend label per band (None for the automatic range label), or None for all automatic. + units: Units of the data the scale colours. + + Raises: + ColourScaleError: If any argument is invalid. + """ + self.name = (name or "").strip() + if not self.name: + raise ColourScaleError("A colour scale needs a name.") + self.thresholds = [float(t) for t in thresholds] + if not self.thresholds: + raise ColourScaleError("A colour scale needs at least one threshold.") + if any(upper <= lower for lower, upper in zip(self.thresholds, self.thresholds[1:])): + raise ColourScaleError("Thresholds must be strictly increasing.") + if labels is not None and len(labels) != self.band_count: + raise ColourScaleError(f"Give one label per band ({self.band_count}), or none.") + self.labels = [str(label) if label else None for label in labels] if labels is not None else None + self.units = units + self.cmap = cmap + + @property + def band_count(self) -> int: + """The number of bands: one more than the number of thresholds.""" + return len(self.thresholds) + 1 + + @property + def cmap(self) -> Union[str, list[str]]: + """The palette name, or the explicit list of hex colours, one per band.""" + return self._cmap + + @cmap.setter + def cmap(self, value: Union[str, Sequence[str]]) -> None: + if isinstance(value, str): + if value not in colormaps: + raise ColourScaleError(f"Unknown colour map '{value}'.") + self._cmap = value + return + colours = [_to_hex_colour(colour) for colour in value] + if len(colours) != self.band_count: + raise ColourScaleError(f"{len(self.thresholds)} threshold(s) make {self.band_count} bands, " + f"but {len(colours)} colour(s) were given.") + self._cmap = colours + + def colours(self) -> list[str]: + """The colour of each band. + + Returns: + list[str]: One hex colour per band. + """ + if isinstance(self._cmap, str): + return sample_colours(self._cmap, self.band_count) + return list(self._cmap) + + def value_range(self, data: Optional[Iterable] = None) -> tuple[float, float]: + """The range the scale spans. + + Args: + data: Values the scale colours. + + Returns: + tuple[float, float]: The data's minimum and maximum, or without data a span around the thresholds. + """ + values = finite_values(data) + if values.size: + low, high = float(values.min()), float(values.max()) + else: + pad = (self.thresholds[-1] - self.thresholds[0]) / max(self.band_count - 2, 1) or 1.0 + low, high = self.thresholds[0] - pad, self.thresholds[-1] + pad + return (low - 0.5, high + 0.5) if low == high else (low, high) + + def cmap_and_norm(self, data: Optional[Iterable] = None) -> tuple[ListedColormap, BoundaryNorm]: + """The matplotlib colour map and normaliser that colour data by this scale. + + Values beyond the end thresholds take the end colours. Pass the data so the end bands run to + its minimum and maximum: a colour bar drawn with `spacing="proportional"` then shows every + band at its true width. + + Args: + data: Values the scale colours. + + Returns: + tuple[ListedColormap, BoundaryNorm]: Pass both to a plot as `cmap` and `norm`. + """ + low, high = self.value_range(data) + t = self.thresholds + first_gap, last_gap = (t[1] - t[0], t[-1] - t[-2]) if len(t) > 1 else (1.0, 1.0) + lowest_edge = low if low < t[0] else t[0] - first_gap + highest_edge = high if high > t[-1] else t[-1] + last_gap + norm = BoundaryNorm([lowest_edge, *t, highest_edge], self.band_count, clip=True) + return ListedColormap(self.colours(), name=self.name), norm + + def band_labels(self) -> list[str]: + """The legend label of each band. + + Returns: + list[str]: The given labels, with ranges such as '< 18', '18 - 21' and '>= 24' where none was given. + """ + t = self.thresholds + ranges = [f"< {_format_number(t[0])}"] + ranges += [f"{_format_number(lower)} - {_format_number(upper)}" for lower, upper in zip(t, t[1:])] + ranges += [f">= {_format_number(t[-1])}"] + given = self.labels or [None] * len(ranges) + return [label or default for label, default in zip(given, ranges)] + + def to_dict(self) -> dict[str, Any]: + """The scale as a JSON-ready dictionary, the inverse of `from_dict`.""" + return {"name": self.name, "thresholds": self.thresholds, "cmap": self._cmap, + "labels": self.labels, "units": self.units} + + @classmethod + def from_dict(cls, data: dict[str, Any]) -> "ColourScale": + """Build a scale from a dictionary made by `to_dict`. + + Args: + data: The saved scale. An older "colours" key is read in place of "cmap". + + Returns: + ColourScale: The scale. + + Raises: + KeyError: If a required key is missing. + ColourScaleError: If the saved values are invalid. + """ + return cls(data["name"], data["thresholds"], data.get("cmap") or data["colours"], + data.get("labels"), data.get("units")) + + def __repr__(self) -> str: + return f"ColourScale({self.name!r}, thresholds={self.thresholds}, cmap={self._cmap!r})" + + +def _to_hex_colour(colour: str) -> str: + """Convert any matplotlib colour to hex, raising ColourScaleError if it is not a colour.""" + try: + return to_hex(to_rgba(colour)) + except ValueError as error: + raise ColourScaleError(f"'{colour}' is not a colour.") from error + + +def _format_number(value: float) -> str: + """Format a threshold to 4 significant figures for a label.""" + return f"{value:.4g}" diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/errors.py b/Python_Engine/Python/src/python_toolkit/colour_scales/errors.py new file mode 100644 index 0000000..440211a --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/errors.py @@ -0,0 +1,5 @@ +"""The error raised for an invalid colour scale or saved scales file.""" + + +class ColourScaleError(ValueError): + """A colour scale definition, or the saved scales file, is invalid.""" diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/jenks.py b/Python_Engine/Python/src/python_toolkit/colour_scales/jenks.py new file mode 100644 index 0000000..bbb547e --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/jenks.py @@ -0,0 +1,68 @@ +"""Fisher-Jenks natural breaks.""" + +import numpy as np + +from python_toolkit.colour_scales.errors import ColourScaleError + +MAX_VALUES = 2000 # larger data is thinned, evenly through its sorted values, before the search + + +def jenks_breaks(values: np.ndarray, bands: int) -> list[float]: + """Split values into the bands with the least total squared deviation from each band's mean. + + Args: + values: Finite values to split. + bands: Number of bands wanted. + + Returns: + list[float]: `bands - 1` breaks; each is the lowest value of the band above it. + + Raises: + ColourScaleError: If there are fewer distinct values than bands. + """ + ordered = np.sort(values) + if ordered.size > MAX_VALUES: + ordered = ordered[np.linspace(0, ordered.size - 1, MAX_VALUES).round().astype(int)] + x, counts = np.unique(ordered, return_counts=True) + if x.size < bands: + raise ColourScaleError("Too few distinct values for that many natural-break bands; use fewer bands.") + band_starts = _best_band_starts(x, counts.astype(float), bands) + return _read_breaks(x, band_starts, bands) + + +def _best_band_starts(x: np.ndarray, weights: np.ndarray, bands: int) -> np.ndarray: + """Dynamic programme over the distinct values `x` (each weighted by how often it occurs). + + Returns: + np.ndarray: `starts[k, j]` is where the last band begins in the best split of x[:j + 1] into k + 1 bands. + """ + n = x.size + cum_w, cum_wx, cum_wx2 = (np.concatenate([[0.0], np.cumsum(a)]) for a in (weights, weights * x, weights * x * x)) + + def squared_deviation(starts: np.ndarray, end: int) -> np.ndarray: + """Squared deviation of x[start:end + 1] about its mean, for each start.""" + w = cum_w[end + 1] - cum_w[starts] + wx = cum_wx[end + 1] - cum_wx[starts] + wx2 = cum_wx2[end + 1] - cum_wx2[starts] + return wx2 - wx * wx / w + + best_cost = np.full((bands, n), np.inf) + band_starts = np.zeros((bands, n), dtype=int) + best_cost[0] = [squared_deviation(np.array([0]), j)[0] for j in range(n)] + for k in range(1, bands): + for j in range(k, n): + starts = np.arange(k, j + 1) + total = best_cost[k - 1, starts - 1] + squared_deviation(starts, j) + pick = int(np.argmin(total)) + best_cost[k, j], band_starts[k, j] = total[pick], starts[pick] + return band_starts + + +def _read_breaks(x: np.ndarray, band_starts: np.ndarray, bands: int) -> list[float]: + """Walk back through the band starts from the last value to read off each break.""" + breaks, end = [], x.size - 1 + for k in range(bands - 1, 0, -1): + start = int(band_starts[k, end]) + breaks.append(float(x[start])) + end = start - 1 + return breaks[::-1] diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/library.py b/Python_Engine/Python/src/python_toolkit/colour_scales/library.py new file mode 100644 index 0000000..03fcb83 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/library.py @@ -0,0 +1,97 @@ +"""The saved colour scales file: one JSON file, one entry per scale name.""" + +import json +from pathlib import Path +from typing import Any, Optional + +from python_toolkit.bhom.logging import CONSOLE_LOGGER +from python_toolkit.colour_scales.colour_scale import ColourScale +from python_toolkit.colour_scales.errors import ColourScaleError + +DEFAULT_LIBRARY_PATH = Path.home() / ".bhom" / "colour_scales.json" + + +def load_scales(path: Optional[Path] = None) -> list[ColourScale]: + """Read the saved scales. + + Args: + path: The saved scales file; defaults to DEFAULT_LIBRARY_PATH. + + Returns: + list[ColourScale]: The saved scales. Entries that cannot be read are logged and skipped, + but never removed from the file. + + Raises: + ColourScaleError: If the file cannot be read or is not a saved scales file. + """ + scales = [] + for entry in _read_entries(path): + try: + scales.append(ColourScale.from_dict(entry)) + except (KeyError, TypeError, ValueError) as error: + CONSOLE_LOGGER.warning(f"Could not read saved scale '{entry.get('name', '?')}': {error}") + return scales + + +def save_scale(scale: ColourScale, path: Optional[Path] = None, overwrite: bool = False, + replaces: Optional[str] = None) -> None: + """Add a scale to the saved scales file. + + Args: + scale: The scale to save. + path: The saved scales file; defaults to DEFAULT_LIBRARY_PATH. + overwrite: Replace a saved scale of the same name. + replaces: The saved name this scale is an edit of. That entry is replaced without needing + `overwrite`, so a renamed scale does not leave its old name behind. + + Raises: + ColourScaleError: If a different scale of the same name is saved and `overwrite` is False. + """ + entries = _read_entries(path) + name_taken = scale.name != replaces and any(entry.get("name") == scale.name for entry in entries) + if name_taken and not overwrite: + raise ColourScaleError(f"A scale named '{scale.name}' already exists.") + others = [entry for entry in entries if entry.get("name") not in (scale.name, replaces)] + _write_entries(path, [*others, scale.to_dict()]) + + +def delete_scale(name: str, path: Optional[Path] = None) -> bool: + """Remove a saved scale. + + Args: + name: Name of the scale to remove. + path: The saved scales file; defaults to DEFAULT_LIBRARY_PATH. + + Returns: + bool: True if a scale was removed, False if none had that name. + """ + entries = _read_entries(path) + others = [entry for entry in entries if entry.get("name") != name] + if len(others) == len(entries): + return False + _write_entries(path, others) + return True + + +def _read_entries(path: Optional[Path]) -> list[dict[str, Any]]: + """The raw scale entries in the file, or [] if there is no file yet.""" + path = Path(path or DEFAULT_LIBRARY_PATH) + if not path.exists(): + return [] + try: + content = json.loads(path.read_text(encoding="utf-8")) + except (OSError, ValueError) as error: + raise ColourScaleError(f"Cannot read the colour scale library {path}: {error}") from error + entries = content.get("scales") if isinstance(content, dict) else content + if not isinstance(entries, list) or not all(isinstance(entry, dict) for entry in entries): + raise ColourScaleError(f"{path} is not a colour scale library.") + return entries + + +def _write_entries(path: Optional[Path], entries: list[dict[str, Any]]) -> None: + """Write the scale entries, via a temporary file so a failed write cannot corrupt the library.""" + path = Path(path or DEFAULT_LIBRARY_PATH) + path.parent.mkdir(parents=True, exist_ok=True) + temporary = path.with_suffix(".tmp") + temporary.write_text(json.dumps({"version": 1, "scales": entries}, indent=2), encoding="utf-8") + temporary.replace(path) diff --git a/Python_Engine/Python/src/python_toolkit/colour_scales/values.py b/Python_Engine/Python/src/python_toolkit/colour_scales/values.py new file mode 100644 index 0000000..d760167 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/colour_scales/values.py @@ -0,0 +1,32 @@ +"""Reading numeric values out of whatever data a colour scale is given.""" + +import math +from typing import Any, Iterable, Optional + +import numpy as np + + +def finite_values(data: Optional[Iterable]) -> np.ndarray: + """Read the finite numbers from any iterable, flattened. + + Args: + data: Values of any shape or type, or None. + + Returns: + np.ndarray: The finite values as floats; None, NaN, infinities and non-numbers are dropped. + """ + if data is None: + return np.empty(0) + try: # fast path: already numeric (or numeric strings) + numbers = np.ravel(np.asarray(data if hasattr(data, "__len__") else list(data), dtype=float)) + except (TypeError, ValueError): # mixed input: keep the numbers, drop the rest + numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) + return numbers[np.isfinite(numbers)] + + +def _to_float(value: Any) -> float: + """Convert a value to a float, or NaN if it is not a number.""" + try: + return float(value) + except (TypeError, ValueError): + return math.nan diff --git a/Python_Engine/Python/src/python_toolkit/palettes/__init__.py b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py new file mode 100644 index 0000000..8cb74ef --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py @@ -0,0 +1,30 @@ +"""Colour palettes: matplotlib's colour maps plus the toolkit's own. + +Importing this package registers the toolkit palettes with matplotlib, so their names work +anywhere a colour map name is accepted: + + palette_names("colourblind") # ['viridis', 'cividis', ..., 'okabe_ito'] + sample_colours("okabe_ito", 4) # four hex colours +""" + +from python_toolkit.palettes.palette import Palette +from python_toolkit.palettes.registry import ( + PaletteGroup, + is_categorical, + palette_names, + register_toolkit_palettes, + sample_colours, +) +from python_toolkit.palettes.toolkit_palettes import TOOLKIT_PALETTES + +register_toolkit_palettes() + +__all__ = [ + "Palette", + "PaletteGroup", + "TOOLKIT_PALETTES", + "is_categorical", + "palette_names", + "register_toolkit_palettes", + "sample_colours", +] diff --git a/Python_Engine/Python/src/python_toolkit/palettes/palette.py b/Python_Engine/Python/src/python_toolkit/palettes/palette.py new file mode 100644 index 0000000..79ffc45 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/palettes/palette.py @@ -0,0 +1,32 @@ +"""A named set of colours that can be registered with matplotlib as a colour map.""" + +from dataclasses import dataclass + +from matplotlib.colors import Colormap, LinearSegmentedColormap, ListedColormap + + +@dataclass(frozen=True) +class Palette: + """A named set of colours. + + Args: + name: Name the palette is registered under in matplotlib. + colours: Hex colours, in order. + categorical: True if each colour is a separate category, False for a continuous gradient. + colourblind_safe: True if the palette is distinguishable with the common colour vision deficiencies. + """ + + name: str + colours: tuple[str, ...] + categorical: bool = False + colourblind_safe: bool = False + + def to_colormap(self) -> Colormap: + """Build the matplotlib colour map for this palette. + + Returns: + Colormap: A ListedColormap for a categorical palette, else a LinearSegmentedColormap. + """ + if self.categorical: + return ListedColormap(list(self.colours), name=self.name) + return LinearSegmentedColormap.from_list(self.name, list(self.colours)) diff --git a/Python_Engine/Python/src/python_toolkit/palettes/registry.py b/Python_Engine/Python/src/python_toolkit/palettes/registry.py new file mode 100644 index 0000000..131804f --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/palettes/registry.py @@ -0,0 +1,92 @@ +"""Registering the toolkit palettes with matplotlib, and listing and sampling palettes by group.""" + +from enum import Enum +from typing import Optional, Union + +import numpy as np +from matplotlib import colormaps +from matplotlib.colors import to_hex + +from python_toolkit.palettes.toolkit_palettes import ( + MATPLOTLIB_CATEGORICAL, + MATPLOTLIB_COLOURBLIND_SAFE, + MATPLOTLIB_CONTINUOUS, + TOOLKIT_PALETTES, +) + + +class PaletteGroup(str, Enum): + """The groups palettes are offered in.""" + + CATEGORICAL = "categorical" + CONTINUOUS = "continuous" + COLOURBLIND = "colourblind" + + +def register_toolkit_palettes() -> None: + """Register each toolkit palette, and its reversed `_r` copy, with matplotlib. + + A name that is already registered is left alone: where matplotlib provides a palette of the same + name (e.g. `okabe_ito` from matplotlib 3.11), matplotlib's is used and the toolkit's is dropped. + This also makes it safe to call more than once. + """ + for palette in TOOLKIT_PALETTES: + if palette.name in colormaps: + continue + cmap = palette.to_colormap() + colormaps.register(cmap, name=palette.name) + colormaps.register(cmap.reversed(), name=f"{palette.name}_r") + + +def palette_names(group: Optional[Union[PaletteGroup, str]] = None) -> list[str]: + """List the palettes in a group. + + Args: + group: The group to list. None lists every registered colour map, including the reversed `_r` copies. + + Returns: + list[str]: Palette names; a group lists base palettes only, without the reversed copies. + """ + if group is None: + return sorted(colormaps, key=str.lower) + return [name for name in _group_members(PaletteGroup(group)) if name in colormaps] + + +def is_categorical(name: str) -> bool: + """Whether a palette, or its reversed copy, is categorical. + + Args: + name: Palette name. + + Returns: + bool: True if each colour of the palette is a separate category. + """ + return name.removesuffix("_r") in _group_members(PaletteGroup.CATEGORICAL) + + +def sample_colours(name: str, count: int) -> list[str]: + """Pick colours from a palette. + + Args: + name: Palette name. + count: Number of colours wanted. + + Returns: + list[str]: `count` hex colours: the first ones of a categorical palette with enough colours, + otherwise spread evenly from one end of the palette to the other. + """ + cmap = colormaps[name] + if is_categorical(name) and count <= cmap.N: + positions = (np.arange(count) + 0.5) / cmap.N + else: + positions = np.linspace(0, 1, count) if count > 1 else [0.5] + return [to_hex(cmap(position)) for position in positions] + + +def _group_members(group: PaletteGroup) -> list[str]: + """The palette names in a group: matplotlib's, then the toolkit's own.""" + if group is PaletteGroup.CATEGORICAL: + return [*MATPLOTLIB_CATEGORICAL, *(p.name for p in TOOLKIT_PALETTES if p.categorical)] + if group is PaletteGroup.CONTINUOUS: + return [*MATPLOTLIB_CONTINUOUS, *(p.name for p in TOOLKIT_PALETTES if not p.categorical)] + return [*MATPLOTLIB_COLOURBLIND_SAFE, *(p.name for p in TOOLKIT_PALETTES if p.colourblind_safe)] diff --git a/Python_Engine/Python/src/python_toolkit/palettes/toolkit_palettes.py b/Python_Engine/Python/src/python_toolkit/palettes/toolkit_palettes.py new file mode 100644 index 0000000..9e151bc --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/palettes/toolkit_palettes.py @@ -0,0 +1,28 @@ +"""The toolkit's own palettes, and the matplotlib colour maps offered alongside them.""" + +from python_toolkit.palettes.palette import Palette + +TOOLKIT_PALETTES: tuple[Palette, ...] = ( + Palette("okabe_ito", ("#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"), + categorical=True, colourblind_safe=True), + Palette("cool_to_warm", ("#3b4cc0", "#8db0fe", "#dddddd", "#f4987a", "#b40426")), + Palette("traffic_light", ("#1a9850", "#fee08b", "#d73027")), + Palette("ltc_heatmap", ("#000004", "#51127c", "#b63679", "#fb8861", "#fcffa4")), + Palette("ltc_maya", ("#5c8286", "#a1b18c", "#e7cca6", "#d98f79", "#b35b5a")), + Palette("ltc_paloma", ("#1a2a40", "#456a73", "#82a69d", "#d9ccb6", "#bf8865")), + Palette("parula", ("#3e26a8", "#484cf0", "#337afd", "#21a3e3", "#14beb8", "#5ecd74", "#cbc128", "#fdcb32", + "#f9fb15")), +) + +MATPLOTLIB_CATEGORICAL: tuple[str, ...] = ( + "Accent", "Dark2", "Paired", "Pastel1", "Pastel2", "Set1", "Set2", "Set3", "tab10", "tab20", "tab20b", "tab20c", +) + +MATPLOTLIB_CONTINUOUS: tuple[str, ...] = ( + "viridis", "plasma", "inferno", "magma", "cividis", "turbo", "Blues", "Greens", "Greys", "Oranges", "Purples", + "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd", "coolwarm", "seismic", "Spectral", "RdYlBu", "RdYlGn", "twilight", + "twilight_shifted", "hsv", +) + +# perceptually uniform, so safe for the common colour vision deficiencies +MATPLOTLIB_COLOURBLIND_SAFE: tuple[str, ...] = ("viridis", "cividis", "plasma", "inferno", "magma") diff --git a/Python_Engine/Python/src/python_toolkit/plot/colour_scale_histogram.py b/Python_Engine/Python/src/python_toolkit/plot/colour_scale_histogram.py new file mode 100644 index 0000000..be55fd0 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/plot/colour_scale_histogram.py @@ -0,0 +1,44 @@ +"""Histogram of data drawn over the bands of a colour scale.""" + +import numpy as np +from matplotlib.figure import Figure + +from python_toolkit.colour_scales import ColourScale + + +def colour_scale_histogram(scale: ColourScale, values: np.ndarray, figsize: tuple[float, float] = (5.6, 1.3), + background: str = "#ffffff", foreground: str = "#000000") -> Figure: + """Plot a histogram of the data over the scale's colours, with a line at each threshold. + + Args: + scale: The colour scale to show. + values: Finite values the scale colours; with none, only the colours and thresholds are drawn. + figsize: Figure size in inches. + background: Figure background colour. + foreground: Colour of the bars, threshold lines and axis. + + Returns: + Figure: The plot. + """ + fig = Figure(figsize=figsize, dpi=100, facecolor=background) + ax = fig.add_axes([0.0, 0.2, 1.0, 0.76], facecolor=background) + cmap, norm = scale.cmap_and_norm() + low, high = scale.value_range(values) + xs = np.linspace(low, high, 400) + ax.imshow(cmap(norm(xs))[np.newaxis, :, :], aspect="auto", extent=(low, high, 0, 1), alpha=0.85, + origin="lower", zorder=0) + if values.size: + counts, edges = np.histogram(values, bins=30, range=(low, high)) + ax.bar(edges[:-1], counts / max(counts.max(), 1), width=np.diff(edges), align="edge", color=foreground, + alpha=0.45, edgecolor=background, linewidth=0.6, zorder=1) + for threshold in scale.thresholds: + if low <= threshold <= high: + ax.axvline(threshold, color=foreground, linewidth=1.2, zorder=2) + ax.set_xlim(low, high) + ax.set_ylim(0, 1.05) + ax.set_yticks([]) + ax.tick_params(labelsize=7, colors=foreground) + for side in ("top", "right", "left"): + ax.spines[side].set_visible(False) + ax.spines["bottom"].set_color(foreground) + return fig diff --git a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py b/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py deleted file mode 100644 index 0575eb4..0000000 --- a/Python_Engine/Python/src/python_toolkit/plot/colour_scales.py +++ /dev/null @@ -1,324 +0,0 @@ -"""Colour scales: data broken into bands at thresholds in data units, coloured by a palette. - -A matplotlib Colormap only knows positions from 0 to 1, so a saved "18 / 21 / 24 degC" band -set drifts whenever the data range changes. A ColourScale keeps its thresholds in data units -and produces the matching (Colormap, Normalize) pair, whatever data it is used on: - - scale = ColourScale("Comfort", thresholds=[18, 21, 24], cmap="coolwarm", - labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") - cmap, norm = scale.mapping() - ax.scatter(x, y, c=room_temperatures, cmap=cmap, norm=norm) - scale.cmap = "okabe_ito" # the colours can change; the thresholds stay - -`cmap` is a palette name (see `python_toolkit.plot.palettes`) or an explicit list of colours, -one per band. -""" - -from __future__ import annotations - -import json -import math -from pathlib import Path -from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union - -import numpy as np -from matplotlib import colormaps -from matplotlib.colors import BoundaryNorm, Colormap, ListedColormap, to_hex, to_rgba - -from python_toolkit.bhom.logging import CONSOLE_LOGGER -from python_toolkit.plot import palettes - -LIBRARY_FILE = Path.home() / ".bhom" / "colour_scales.json" -SUGGESTION_METHODS = ("equal", "quantile", "jenks", "nice", "log") -JENKS_MAX_VALUES = 2000 # larger data is thinned (evenly through its sorted values) before the search - - -class ColourScaleError(ValueError): - """A colour scale definition, or the saved library, is invalid.""" - - -class ColourScale: - """A named set of bands split at `thresholds` (data units), coloured by `cmap`.""" - - def __init__(self, name: str, thresholds: Sequence[float], cmap: Union[str, Sequence[str]] = "viridis", - labels: Optional[Sequence[Optional[str]]] = None, units: Optional[str] = None): - self.name = (name or "").strip() - if not self.name: - raise ColourScaleError("A colour scale needs a name.") - self.thresholds = [float(t) for t in thresholds] - if not self.thresholds: - raise ColourScaleError("A colour scale needs at least one threshold.") - if any(b <= a for a, b in zip(self.thresholds, self.thresholds[1:])): - raise ColourScaleError("Thresholds must be strictly increasing.") - if labels is not None and len(labels) != self.bands: - raise ColourScaleError(f"Give one label per band ({self.bands}), or none.") - self.labels = [str(l) if l else None for l in labels] if labels is not None else None - self.units = units - self.cmap = cmap - - @property - def bands(self) -> int: - return len(self.thresholds) + 1 - - @property - def cmap(self) -> Union[str, List[str]]: - return self._cmap - - @cmap.setter - def cmap(self, value: Union[str, Sequence[str]]) -> None: - if isinstance(value, str): - if value not in colormaps: - raise ColourScaleError(f"Unknown colour map '{value}'.") - self._cmap = value - return - colours = [_hex(c) for c in value] - if len(colours) != self.bands: - raise ColourScaleError(f"{len(self.thresholds)} threshold(s) make {self.bands} bands, " - f"but {len(colours)} colour(s) were given.") - self._cmap = colours - - def colours(self) -> List[str]: - """One hex colour per band.""" - return list(self._cmap) if not isinstance(self._cmap, str) else palettes.sample(self._cmap, self.bands) - - def value_range(self, data: Optional[Iterable] = None) -> Tuple[float, float]: - """The data range, or a span around the thresholds without data.""" - values = clean_data(data) - if values.size: - lo, hi = float(values.min()), float(values.max()) - else: - pad = (self.thresholds[-1] - self.thresholds[0]) / max(self.bands - 2, 1) or 1.0 - lo, hi = self.thresholds[0] - pad, self.thresholds[-1] + pad - return (lo - 0.5, hi + 0.5) if lo == hi else (lo, hi) - - def mapping(self, data: Optional[Iterable] = None) -> Tuple[Colormap, BoundaryNorm]: - """The colormap and normaliser to colour any data with; values beyond the ends take the end colours. - - Pass the data so the end bands run to its minimum and maximum: a colour bar drawn with - `spacing="proportional"` then shows every band at its true width, as the builder preview does.""" - lo, hi = self.value_range(data) - t = self.thresholds - first_gap, last_gap = (t[1] - t[0], t[-1] - t[-2]) if len(t) > 1 else (1.0, 1.0) - edges = [lo if lo < t[0] else t[0] - first_gap] + t + [hi if hi > t[-1] else t[-1] + last_gap] - return ListedColormap(self.colours(), name=self.name), BoundaryNorm(edges, self.bands, clip=True) - - def band_labels(self) -> List[str]: - """Labels as given, else ranges such as '< 18', '18 - 21', '>= 24'.""" - t = self.thresholds - auto = [f"< {_fmt(t[0])}"] + [f"{_fmt(a)} - {_fmt(b)}" for a, b in zip(t, t[1:])] + [f">= {_fmt(t[-1])}"] - given = self.labels or [None] * len(auto) - return [g or a for g, a in zip(given, auto)] - - def to_dict(self) -> Dict[str, Any]: - return {"name": self.name, "thresholds": self.thresholds, "cmap": self._cmap, - "labels": self.labels, "units": self.units} - - @classmethod - def from_dict(cls, data: Dict[str, Any]) -> "ColourScale": - # "colours" is the older name for the colour list - return cls(data["name"], data["thresholds"], data.get("cmap") or data["colours"], - data.get("labels"), data.get("units")) - - def __repr__(self) -> str: - return f"ColourScale({self.name!r}, thresholds={self.thresholds}, cmap={self._cmap!r})" - - -# --------------------------------------------------------------------------- -# Suggesting thresholds from data -# --------------------------------------------------------------------------- - -def thresholds(data: Iterable, bands: int, method: str = "nice") -> List[float]: - """Inner boundaries splitting the data into `bands` bands. - - equal: equal-width bands across the data range - quantile: roughly the same number of values in each band - jenks: natural breaks; the bands that minimise the spread of values within each band - nice: equal-width bands on rounded 1 / 2 / 5 x 10^n steps - log: bands of equal ratio (each break a fixed multiple of the last), rounded to 3 significant - figures; needs every value above zero - """ - if bands < 2: - raise ColourScaleError("A threshold scale needs at least 2 bands.") - if method not in SUGGESTION_METHODS: - raise ColourScaleError(f"Method must be one of {SUGGESTION_METHODS}, not '{method}'.") - values = clean_data(data) - if values.size == 0: - raise ColourScaleError("No numeric values to suggest thresholds from.") - lo, hi = float(values.min()), float(values.max()) - if lo == hi: - return [lo + i for i in range(1, bands)] - - if method == "equal": - return [float(v) for v in np.linspace(lo, hi, bands + 1)[1:-1]] - if method == "quantile": - cuts = np.quantile(values, np.linspace(0, 1, bands + 1)[1:-1]) - unique = sorted(set(float(c) for c in cuts)) - if len(unique) < bands - 1: - raise ColourScaleError("Too many repeated values for that many quantile bands; use fewer bands.") - return unique - if method == "jenks": - return _jenks_thresholds(values, bands) - if method == "log": - if lo <= 0: - raise ColourScaleError("Logarithmic breaks need every value above zero; use another break method.") - cuts = [float(f"{v:.3g}") for v in np.geomspace(lo, hi, bands + 1)[1:-1]] - if any(b <= a for a, b in zip(cuts, cuts[1:])) or cuts[0] <= lo or cuts[-1] >= hi: - raise ColourScaleError("The data range is too narrow for that many logarithmic bands; use fewer bands.") - return cuts - return _nice_thresholds(lo, hi, bands - 1) - - -def _jenks_thresholds(values: np.ndarray, bands: int) -> List[float]: - """Fisher-Jenks natural breaks: the split into `bands` runs of sorted values with the least - total squared deviation from each run's mean. Each break is the lowest value of the band above it.""" - ordered = np.sort(values) - if ordered.size > JENKS_MAX_VALUES: - ordered = ordered[np.linspace(0, ordered.size - 1, JENKS_MAX_VALUES).round().astype(int)] - x, counts = np.unique(ordered, return_counts=True) - n = x.size - if n < bands: - raise ColourScaleError("Too few distinct values for that many natural-break bands; use fewer bands.") - - w = counts.astype(float) - cw, cwx, cwx2 = (np.concatenate([[0.0], np.cumsum(a)]) for a in (w, w * x, w * x * x)) - - def cost(starts: np.ndarray, end: int) -> np.ndarray: - """Squared deviation of x[start:end + 1] about its mean, for each start.""" - sw, swx, swx2 = cw[end + 1] - cw[starts], cwx[end + 1] - cwx[starts], cwx2[end + 1] - cwx2[starts] - return swx2 - swx * swx / sw - - best = np.full((bands, n), np.inf) - first = np.zeros((bands, n), dtype=int) # where the last band starts, for the best split of x[:j + 1] - for j in range(n): - best[0, j] = cost(np.array([0]), j)[0] - for k in range(1, bands): - for j in range(k, n): - starts = np.arange(k, j + 1) - total = best[k - 1, starts - 1] + cost(starts, j) - pick = int(np.argmin(total)) - best[k, j], first[k, j] = total[pick], starts[pick] - - cuts, end = [], n - 1 - for k in range(bands - 1, 0, -1): - start = int(first[k, end]) - cuts.append(float(x[start])) - end = start - 1 - return cuts[::-1] - - -def _nice_thresholds(lo: float, hi: float, wanted: int) -> List[float]: - """Rounded breaks (multiples of 1, 2, 2.5 or 5 x 10^n) strictly inside the data range. - - Picks the step with the fewest breaks that is still at least `wanted`, then keeps `wanted` of them spread - evenly from the first to the last, so every band contains data and the end bands stay small. Where the - step does not divide evenly, some bands are two steps wide.""" - exponent = math.floor(math.log10((hi - lo) / (wanted + 1))) - best = None - for power in (exponent - 1, exponent, exponent + 1): - for factor in (1, 2, 2.5, 5): - step = factor * 10 ** power - inner = [round(k * step, 10) for k in range(math.floor(lo / step) + 1, math.ceil(hi / step))] - if len(inner) < wanted: # always return the number of breaks asked for - continue - score = abs(len(inner) - wanted) + (0.5 if factor == 2.5 else 0.0) # prefer rounder steps - if best is None or score < best[0]: - best = (score, inner) - if best is None: # range too narrow for rounded breaks - return [float(v) for v in np.linspace(lo, hi, wanted + 2)[1:-1]] - inner = best[1] - return [inner[i] for i in np.linspace(0, len(inner) - 1, wanted).round().astype(int)] - - -# --------------------------------------------------------------------------- -# Saved scales: one JSON file, one entry per name -# --------------------------------------------------------------------------- - -def load_scales(path: Optional[Path] = None) -> List[ColourScale]: - """Saved scales; entries that cannot be read are logged and skipped (never deleted from the file).""" - scales = [] - for entry in _read(path): - try: - scales.append(ColourScale.from_dict(entry)) - except (KeyError, TypeError, ValueError) as e: - CONSOLE_LOGGER.warning(f"Could not read saved scale '{entry.get('name', '?')}': {e}") - return scales - - -def save_scale(scale: ColourScale, path: Optional[Path] = None, overwrite: bool = False, - replaces: Optional[str] = None) -> None: - """Add a scale to the saved file; an existing name is only replaced with `overwrite`. - - `replaces` is the saved name this scale is an edit of: that entry is replaced (so a renamed - scale does not leave its old name behind) without needing `overwrite`.""" - path = Path(path or LIBRARY_FILE) - entries = _read(path) - others = [e for e in entries if e.get("name") not in (scale.name, replaces)] - clash = scale.name != replaces and any(e.get("name") == scale.name for e in entries) - if clash and not overwrite: - raise ColourScaleError(f"A scale named '{scale.name}' already exists.") - _write(path, others + [scale.to_dict()]) - - -def delete_scale(name: str, path: Optional[Path] = None) -> bool: - """Remove a saved scale by name; False if there was none of that name.""" - path = Path(path or LIBRARY_FILE) - entries = _read(path) - others = [e for e in entries if e.get("name") != name] - if len(others) == len(entries): - return False - _write(path, others) - return True - - -def _write(path: Path, entries: List[Dict[str, Any]]) -> None: - path.parent.mkdir(parents=True, exist_ok=True) - tmp = path.with_suffix(".tmp") - tmp.write_text(json.dumps({"version": 1, "scales": entries}, indent=2), encoding="utf-8") - tmp.replace(path) - - -def _read(path: Optional[Path]) -> List[Dict[str, Any]]: - path = Path(path or LIBRARY_FILE) - if not path.exists(): - return [] - try: - raw = json.loads(path.read_text(encoding="utf-8")) - except (OSError, ValueError) as e: - raise ColourScaleError(f"Cannot read the colour scale library {path}: {e}") from e - entries = raw.get("scales") if isinstance(raw, dict) else raw - if not isinstance(entries, list) or not all(isinstance(e, dict) for e in entries): - raise ColourScaleError(f"{path} is not a colour scale library.") - return entries - - -# --------------------------------------------------------------------------- -# Helpers -# --------------------------------------------------------------------------- - -def clean_data(data: Optional[Iterable]) -> np.ndarray: - """Finite float values from any iterable; None, NaN and non-numbers are dropped.""" - if data is None: - return np.empty(0) - try: # fast path: already numeric (or numeric strings) - numbers = np.ravel(np.asarray(data if hasattr(data, "__len__") else list(data), dtype=float)) - except (TypeError, ValueError): # mixed input: keep the numbers, drop the rest - numbers = np.array([_to_float(v) for v in np.ravel(np.asarray(list(data), dtype=object))], dtype=float) - return numbers[np.isfinite(numbers)] - - -def _hex(colour: str) -> str: - try: - return to_hex(to_rgba(colour)) - except ValueError as e: - raise ColourScaleError(f"'{colour}' is not a colour.") from e - - -def _to_float(value) -> float: - try: - return float(value) - except (TypeError, ValueError): - return math.nan - - -def _fmt(value: float) -> str: - return f"{value:.4g}" diff --git a/Python_Engine/Python/src/python_toolkit/plot/palettes.py b/Python_Engine/Python/src/python_toolkit/plot/palettes.py deleted file mode 100644 index 1431f46..0000000 --- a/Python_Engine/Python/src/python_toolkit/plot/palettes.py +++ /dev/null @@ -1,69 +0,0 @@ -"""Colour palettes: matplotlib's colour maps plus the toolkit's own, always registered. - -Importing this module adds the toolkit palettes (and their reversed `_r` copies) to -matplotlib, so any palette name works anywhere a colour map name is accepted: - - palettes.names("colourblind") # ['viridis', 'cividis', ..., 'okabe_ito'] - palettes.sample("okabe_ito", 4) # four hex colours -""" - -from typing import List, Optional - -import numpy as np -from matplotlib import colormaps -from matplotlib.colors import LinearSegmentedColormap, ListedColormap, to_hex - -# The toolkit's own palettes: name -> (kind, colour-blind safe, colours). -CUSTOM = { - "okabe_ito": ("categorical", True, ["#E69F00", "#56B4E9", "#009E73", "#F0E442", "#0072B2", "#D55E00", "#CC79A7"]), - "cool_to_warm": ("continuous", False, ["#3b4cc0", "#8db0fe", "#dddddd", "#f4987a", "#b40426"]), - "traffic_light": ("continuous", False, ["#1a9850", "#fee08b", "#d73027"]), - "ltc_heatmap": ("continuous", False, ["#000004", "#51127c", "#b63679", "#fb8861", "#fcffa4"]), - "ltc_maya": ("continuous", False, ["#5c8286", "#a1b18c", "#e7cca6", "#d98f79", "#b35b5a"]), - "ltc_paloma": ("continuous", False, ["#1a2a40", "#456a73", "#82a69d", "#d9ccb6", "#bf8865"]), - "parula": ("continuous", False, ["#3e26a8", "#484cf0", "#337afd", "#21a3e3", "#14beb8", "#5ecd74", "#cbc128", "#fdcb32", "#f9fb15"]), -} - -# matplotlib colour maps by kind; the toolkit palettes are added below. -KINDS = { - "categorical": ["Accent", "Dark2", "Paired", "Pastel1", "Pastel2", "Set1", "Set2", "Set3", - "tab10", "tab20", "tab20b", "tab20c"], - - "continuous": ["viridis", "plasma", "inferno", "magma", "cividis", "turbo", "Blues", "Greens", "Greys", - "Oranges", "Purples", "Reds", "YlGn", "YlGnBu", "YlOrBr", "YlOrRd", "coolwarm", "seismic", - "Spectral", "RdYlBu", "RdYlGn", "twilight", "twilight_shifted", "hsv"], - - # perceptually uniform maps; matplotlib's own, so safe for the common colour vision deficiencies - "colourblind": ["viridis", "cividis", "plasma", "inferno", "magma"], -} - -for _name, (_kind, _safe, _colours) in CUSTOM.items(): - if _name not in colormaps: - _cmap = (ListedColormap(_colours, name=_name) if _kind == "categorical" - else LinearSegmentedColormap.from_list(_name, _colours)) - colormaps.register(_cmap, name=_name) - colormaps.register(_cmap.reversed(), name=f"{_name}_r") - KINDS[_kind].append(_name) - if _safe: - KINDS["colourblind"].append(_name) - - -def names(kind: Optional[str] = None) -> List[str]: - """Colour map names of a kind ("categorical", "continuous", "colourblind"), without reversed copies. - - With no kind, every registered colour map including the reversed `_r` copies. - """ - if kind is None: - return sorted(colormaps, key=str.lower) - return [name for name in KINDS[kind] if name in colormaps] - - -def sample(name: str, count: int) -> List[str]: - """`count` hex colours from a palette: the first ones for a categorical palette, else evenly spread.""" - cmap = colormaps[name] - base = name[:-2] if name.endswith("_r") else name - if base in KINDS["categorical"] and count <= cmap.N: - points = (np.arange(count) + 0.5) / cmap.N - else: - points = np.linspace(0, 1, count) if count > 1 else [0.5] - return [to_hex(cmap(p)) for p in points] diff --git a/Python_Engine/Python/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py index 7bf2400..01947cc 100644 --- a/Python_Engine/Python/tests/test_colour_scale_builder.py +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -5,9 +5,9 @@ from python_toolkit.bhom_tkinter.bhom_base_window import BHoMBaseWindow from python_toolkit.bhom_tkinter.widgets.cmap_selector import CmapSelector from python_toolkit.bhom_tkinter.windows import ColourScaleBuilder -from python_toolkit.bhom_tkinter.windows.colour_scale_builder import preview_figure -from python_toolkit.plot import palettes -from python_toolkit.plot.colour_scales import ColourScale, load_scales, save_scale +from python_toolkit.colour_scales import ColourScale, load_scales, save_scale +from python_toolkit.palettes import sample_colours +from python_toolkit.plot.colour_scale_histogram import colour_scale_histogram @pytest.fixture(scope="module") @@ -57,7 +57,7 @@ def test_builder_saves_labels(host, library): saved = [] builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library_path=library, on_save=saved.append) builder.name.set("Comfort") - builder._band_rows[0]["label"].set("Cold") + builder._band_rows[0].label.set("Cold") builder._save() scale = load_scales(library)[0] assert saved and saved[0].name == "Comfort" @@ -66,7 +66,7 @@ def test_builder_saves_labels(host, library): def test_builder_reports_bad_thresholds_without_saving(host, library, warnings_shown): builder = ColourScaleBuilder(host, data=[18, 21, 24, 27], library_path=library) - builder._band_rows[0]["upper"].set("warm") + builder._band_rows[0].upper.set("warm") builder._save() assert builder.saved_scale is None and "not a number" in builder.status.get() assert warnings_shown and "not a number" in warnings_shown[0][0] # shown in a pop-up, not only in the window @@ -99,20 +99,20 @@ def test_builder_log_breaks_and_edit(host, library): def test_preview_with_and_without_data(): scale = ColourScale("T", [20, 25], ["#0000ff", "#00ff00", "#ff0000"]) - assert preview_figure(scale, np.linspace(16, 30, 50)).axes - assert preview_figure(scale, np.array([])).axes + assert colour_scale_histogram(scale, np.linspace(16, 30, 50)).axes + assert colour_scale_histogram(scale, np.array([])).axes def test_builder_starts_from_a_palette_and_recolours(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 50), library_path=library, palette="magma") assert builder.palette.get() == "magma" - assert [r["colour"].get() for r in builder._band_rows] == palettes.sample("magma", 5) + assert [r.colour.get() for r in builder._band_rows] == sample_colours("magma", 5) assert builder.current_scale().cmap == "magma" # untouched band colours stay a palette reference builder.palette.set("traffic_light") builder._recolour() scale = builder.current_scale() assert scale.cmap == "traffic_light" and scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) - builder._band_rows[0]["colour"].set("#123456") + builder._band_rows[0].colour.set("#123456") assert builder.current_scale().cmap[0] == "#123456" # a hand-picked colour makes it an explicit list @@ -140,23 +140,23 @@ def test_end_to_end_palette_to_saved_scale_to_colours(host, library): scale = load_scales(library)[0] assert scale.cmap == "okabe_ito" and scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) - cmap, norm = scale.mapping() + cmap, norm = scale.cmap_and_norm() colours = {to_hex(cmap(norm(v))) for v in data} - assert colours == set(palettes.sample("okabe_ito", 5)) # every band is used, in the palette's colours + assert colours == set(sample_colours("okabe_ito", 5)) # every band is used, in the palette's colours scale.cmap = "viridis" # swap the colours; the breaks hold - assert scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) and scale.colours() == palettes.sample("viridis", 5) + assert scale.thresholds == pytest.approx([17.5, 20, 25, 27.5]) and scale.colours() == sample_colours("viridis", 5) def test_bands_and_breaks_update_the_scale_without_a_button(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) assert len(builder._band_rows) == 5 builder.band_count.set(3) # what the spinbox does when changed - builder._run_auto_suggest() # what fires once typing has paused + builder._run_scheduled_suggestion() # what fires once typing has paused assert len(builder._band_rows) == 3 and builder.current_scale().thresholds == pytest.approx([20, 25]) builder.method.set("equal") builder.method.combobox.event_generate("<>") - builder._run_auto_suggest() + builder._run_scheduled_suggestion() assert builder.current_scale().thresholds == pytest.approx([20.6667, 25.3333], abs=1e-3) assert len(builder._band_rows) == 3 and builder.band_count.get() == 3 # showing the count does not loop @@ -166,10 +166,10 @@ def test_typing_in_bands_waits_for_the_pause(host, library): builder.band_count.set("1") # first keystroke of "12": nothing happens yet assert len(builder._band_rows) == 5 and builder._suggest_job is not None builder.band_count.set("12") - builder._run_auto_suggest() + builder._run_scheduled_suggestion() assert len(builder._band_rows) == 12 builder.band_count.set("99") # out of range: ignored, bands stay as they are - builder._run_auto_suggest() + builder._run_scheduled_suggestion() assert len(builder._band_rows) == 12 @@ -182,30 +182,30 @@ def test_bands_and_breaks_are_locked_without_data(host, library): def test_changing_the_bands_keeps_what_was_filled_in(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) for i, name in enumerate(["Cold", "Cool", "Comfy", "Warm"]): - builder._band_rows[i]["label"].set(name) - builder._band_rows[1]["colour"].set("#123456") + builder._band_rows[i].label.set(name) + builder._band_rows[1].colour.set("#123456") builder.band_count.set(4) - builder._run_auto_suggest() + builder._run_scheduled_suggestion() scale = builder.current_scale() - assert scale.bands == 4 and scale.labels == ["Cold", "Cool", "Comfy", "Warm"] + assert scale.band_count == 4 and scale.labels == ["Cold", "Cool", "Comfy", "Warm"] assert scale.colours()[1] == "#123456" # the hand-picked colour stays builder.band_count.set(6) # new bands start empty and take palette colours - builder._run_auto_suggest() + builder._run_scheduled_suggestion() scale = builder.current_scale() assert scale.labels[:4] == ["Cold", "Cool", "Comfy", "Warm"] and scale.labels[4:] == [None, None] - assert scale.colours()[1] == "#123456" and scale.colours()[5] == palettes.sample("viridis", 6)[5] + assert scale.colours()[1] == "#123456" and scale.colours()[5] == sample_colours("viridis", 6)[5] def test_changing_the_bands_recolours_untouched_colours(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) builder.band_count.set(3) - builder._run_auto_suggest() + builder._run_scheduled_suggestion() assert builder.current_scale().cmap == "viridis" # still a palette reference, resampled for 3 bands def test_thresholds_spin_in_round_steps(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) - spin = builder._band_rows[0]["upper"].spinbox + spin = builder._band_rows[0].upper.spinbox assert float(spin.cget("increment")) == 0.1 # about 1% of the 14-wide range, rounded for _ in range(5): spin.event_generate("<>") @@ -214,10 +214,10 @@ def test_thresholds_spin_in_round_steps(host, library): def test_split_a_band_adds_one_between_its_ends(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) # breaks 17.5 20 25 27.5 - builder._band_rows[1]["label"].set("Cool") + builder._band_rows[1].label.set("Cool") builder._split_band(1) # the band 17.5 to 20 becomes 17.5 to 18.75 and 18.75 to 20 scale = builder.current_scale() - assert scale.thresholds == pytest.approx([17.5, 18.75, 20, 25, 27.5]) and scale.bands == 6 + assert scale.thresholds == pytest.approx([17.5, 18.75, 20, 25, 27.5]) and scale.band_count == 6 assert scale.labels == [None, "Cool", None, None, None, None] # the label stays with the lower half assert builder.band_count.get() == 6 assert scale.cmap == "viridis" # still a palette, spread over six bands @@ -234,8 +234,8 @@ def test_split_the_open_ends_against_the_data(host, library): def test_remove_a_band_merges_its_range_into_the_next(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) for i, name in enumerate(["a", "b", "c", "d", "e"]): - builder._band_rows[i]["label"].set(name) - builder._band_rows[2]["colour"].set("#123456") # a hand-picked colour, which makes colours explicit + builder._band_rows[i].label.set(name) + builder._band_rows[2].colour.set("#123456") # a hand-picked colour, which makes colours explicit builder._remove_band(1) scale = builder.current_scale() assert scale.thresholds == pytest.approx([17.5, 25, 27.5]) and scale.labels == ["a", "c", "d", "e"] # "c" now starts at 17.5 @@ -247,20 +247,20 @@ def test_remove_a_band_merges_its_range_into_the_next(host, library): def test_bands_cannot_go_below_two_or_above_the_maximum(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) builder.band_count.set(2) - builder._run_auto_suggest() - assert "disabled" in builder._band_rows[0]["remove"].state() + builder._run_scheduled_suggestion() + assert "disabled" in builder._band_rows[0].remove.state() builder._remove_band(0) assert len(builder._band_rows) == 2 builder.band_count.set(24) - builder._run_auto_suggest() - assert "disabled" in builder._band_rows[0]["split"].state() + builder._run_scheduled_suggestion() + assert "disabled" in builder._band_rows[0].split.state() builder._split_band(0) assert len(builder._band_rows) == 24 def test_split_refuses_a_bad_threshold_without_changing_the_table(host, library): builder = ColourScaleBuilder(host, data=np.linspace(16, 30, 200), library_path=library) - builder._band_rows[0]["upper"].set("warm") + builder._band_rows[0].upper.set("warm") builder._split_band(1) assert len(builder._band_rows) == 5 and "not a number" in builder.status.get() diff --git a/Python_Engine/Python/tests/test_colour_scales.py b/Python_Engine/Python/tests/test_colour_scales.py index 1a8598b..3d7cd58 100644 --- a/Python_Engine/Python/tests/test_colour_scales.py +++ b/Python_Engine/Python/tests/test_colour_scales.py @@ -5,38 +5,53 @@ from matplotlib import colormaps from matplotlib.colors import to_hex -from python_toolkit.plot import colour_scales, palettes -from python_toolkit.plot.colour_scales import ( +from python_toolkit.colour_scales import ( + BreakMethod, ColourScale, ColourScaleError, + delete_scale, + finite_values, load_scales, save_scale, + suggest_thresholds, ) +from python_toolkit.palettes import TOOLKIT_PALETTES, palette_names, sample_colours COMFORT = dict(thresholds=[18, 21, 24], cmap=["#0000ff", "#00ffff", "#00ff00", "#ff0000"], labels=["Cold", "Cool", "Comfortable", "Hot"], units="degC") def colour_of(scale, value): - cmap, norm = scale.mapping() + cmap, norm = scale.cmap_and_norm() return to_hex(cmap(norm(value))) # -- palettes ------------------------------------------------------------------ def test_toolkit_palettes_are_always_registered(): - for name, (kind, _safe, _colours) in palettes.CUSTOM.items(): - assert name in colormaps and f"{name}_r" in colormaps - assert name in palettes.names(kind) + for palette in TOOLKIT_PALETTES: + assert palette.name in colormaps and f"{palette.name}_r" in colormaps + assert palette.name in palette_names("categorical" if palette.categorical else "continuous") assert isinstance(colormaps["okabe_ito"], type(colormaps["Set1"])) # discrete, like the other categorical maps - assert "okabe_ito" in palettes.names("colourblind") and "ltc_maya" not in palettes.names("colourblind") - assert "viridis_r" in palettes.names() and "viridis_r" not in palettes.names("continuous") + assert "okabe_ito" in palette_names("colourblind") and "ltc_maya" not in palette_names("colourblind") + assert "viridis_r" in palette_names() and "viridis_r" not in palette_names("continuous") + + +def test_a_palette_matplotlib_already_has_is_not_replaced(monkeypatch): + from python_toolkit.palettes import Palette, registry + + matplotlib_viridis = colormaps["viridis"] + monkeypatch.setattr(registry, "TOOLKIT_PALETTES", (Palette("viridis", ("#000000", "#ffffff")),)) + registry.register_toolkit_palettes() + assert colormaps["viridis"].colors == matplotlib_viridis.colors def test_sample_takes_the_first_colours_of_a_categorical_palette(): - assert palettes.sample("okabe_ito", 3) == ["#e69f00", "#56b4e9", "#009e73"] - assert palettes.sample("magma", 3)[0] == "#000004" - assert len(palettes.sample("traffic_light", 7)) == 7 and len(palettes.sample("viridis", 1)) == 1 + # okabe_ito is matplotlib's from 3.11 (8 colours, black first), else the toolkit's 7 + okabe_ito = [to_hex(c) for c in colormaps["okabe_ito"].colors] + assert sample_colours("okabe_ito", 3) == okabe_ito[:3] + assert sample_colours("magma", 3)[0] == "#000004" + assert len(sample_colours("traffic_light", 7)) == 7 and len(sample_colours("viridis", 1)) == 1 # -- thresholds hold in data units, whatever data is passed in ---------------- @@ -59,9 +74,9 @@ def test_band_labels(): def test_changing_the_palette_keeps_the_breaks(): scale = ColourScale("Heat", [10, 20, 30], "viridis") - assert scale.colours() == palettes.sample("viridis", 4) + assert scale.colours() == sample_colours("viridis", 4) scale.cmap = "okabe_ito" - assert scale.thresholds == [10, 20, 30] and scale.colours() == palettes.sample("okabe_ito", 4) + assert scale.thresholds == [10, 20, 30] and scale.colours() == sample_colours("okabe_ito", 4) scale.cmap = ["red", "green", "blue", "black"] assert scale.colours()[0] == "#ff0000" with pytest.raises(ColourScaleError, match="4 bands"): @@ -93,26 +108,26 @@ def test_validation(kwargs, message): def test_thresholds_methods(): data = np.concatenate([np.full(90, 20.0), np.linspace(20, 30, 10)]) - assert colour_scales.thresholds([0, 100], 4, "equal") == [25, 50, 75] - assert colour_scales.thresholds([0.3, 9.7], 5, "nice") == [2, 4, 6, 8] + assert suggest_thresholds([0, 100], 4, "equal") == [25, 50, 75] + assert suggest_thresholds([0.3, 9.7], 5, "nice") == [2, 4, 6, 8] with pytest.raises(ColourScaleError, match="repeated values"): - colour_scales.thresholds(data, 4, "quantile") - q = colour_scales.thresholds(np.arange(100), 4, "quantile") + suggest_thresholds(data, 4, "quantile") + q = suggest_thresholds(np.arange(100), 4, "quantile") assert len(q) == 3 and q[0] < q[1] < q[2] - assert colour_scales.thresholds([1, None, "x", float("nan"), 3], 2, "equal") == [2] + assert suggest_thresholds([1, None, "x", float("nan"), 3], 2, "equal") == [2] def test_log_thresholds_have_equal_ratios(): - thresholds = colour_scales.thresholds([1, 1000], 3, "log") + thresholds = suggest_thresholds([1, 1000], 3, "log") assert thresholds == pytest.approx([10, 100]) - spread = colour_scales.thresholds(np.geomspace(0.5, 4000, 50), 5, "log") + spread = suggest_thresholds(np.geomspace(0.5, 4000, 50), 5, "log") ratios = [b / a for a, b in zip(spread, spread[1:])] assert len(spread) == 4 and ratios == pytest.approx([ratios[0]] * 3, rel=0.02) for data in ([0, 10, 100], [-5, 10, 100]): with pytest.raises(ColourScaleError, match="above zero"): - colour_scales.thresholds(data, 3, "log") + suggest_thresholds(data, 3, "log") with pytest.raises(ColourScaleError, match="too narrow"): - colour_scales.thresholds([1.0, 1.001], 5, "log") + suggest_thresholds([1.0, 1.001], 5, "log") @pytest.mark.parametrize("data,bands,expected", [ @@ -122,7 +137,7 @@ def test_log_thresholds_have_equal_ratios(): ([1000, 250000], 5, [50000, 100000, 150000, 200000]), ]) def test_nice_thresholds_fall_inside_the_data(data, bands, expected): - thresholds = colour_scales.thresholds(data, bands, "nice") + thresholds = suggest_thresholds(data, bands, "nice") assert thresholds == pytest.approx(expected) assert all(min(data) < t < max(data) for t in thresholds) @@ -183,21 +198,17 @@ def test_corrupt_file_raises(tmp_path): @pytest.mark.parametrize("bands", [2, 3, 4, 5, 6, 8]) def test_suggestions_always_give_the_number_of_bands_asked_for(method, bands): data = np.random.default_rng(1).normal(22, 3, 300) - assert len(colour_scales.thresholds(data, bands, method)) == bands - 1 - assert len(colour_scales.thresholds([16, 30], bands, "nice")) == bands - 1 - + assert len(suggest_thresholds(data, bands, method)) == bands - 1 + assert len(suggest_thresholds([16, 30], bands, "nice")) == bands - 1 -def test_clean_data_handles_numeric_and_mixed_input(): - from python_toolkit.plot.colour_scales import clean_data - assert clean_data(np.array([[1, 2], [3, np.nan]])).tolist() == [1.0, 2.0, 3.0] - assert clean_data([1, None, "x", float("inf"), "4"]).tolist() == [1.0, 4.0] - assert clean_data(v for v in (1, 2)).tolist() == [1.0, 2.0] +def test_finite_values_handles_numeric_and_mixed_input(): + assert finite_values(np.array([[1, 2], [3, np.nan]])).tolist() == [1.0, 2.0, 3.0] + assert finite_values([1, None, "x", float("inf"), "4"]).tolist() == [1.0, 4.0] + assert finite_values(v for v in (1, 2)).tolist() == [1.0, 2.0] def test_save_scale_replaces_the_scale_it_edits_even_when_renamed(tmp_path): - from python_toolkit.plot.colour_scales import ColourScaleError, delete_scale - path = tmp_path / "scales.json" save_scale(ColourScale("A", [1, 2], "viridis"), path) save_scale(ColourScale("B", [1, 2], "viridis"), path) @@ -208,3 +219,9 @@ def test_save_scale_replaces_the_scale_it_edits_even_when_renamed(tmp_path): save_scale(ColourScale("B", [5, 6], "viridis"), path, replaces="B") # same name: a plain edit assert delete_scale("B", path) and not delete_scale("B", path) assert [s.name for s in load_scales(path)] == ["C"] + + +def test_suggest_thresholds_accepts_a_break_method_or_its_name(): + assert suggest_thresholds([0, 100], 4, BreakMethod.EQUAL) == suggest_thresholds([0, 100], 4, "equal") + with pytest.raises(ColourScaleError, match="Method must be one of"): + suggest_thresholds([0, 100], 4, "wobbly") From c7fab048c4eb5462be4146600d14e7070dc98102 Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Tue, 17 Nov 2026 11:22:22 +0000 Subject: [PATCH 6/8] fixed tests --- .../bhom_tkinter/bhom_window_shell.py | 20 +++++++++++++++++++ .../bhom_tkinter/widgets/spinbox.py | 4 +++- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/bhom_window_shell.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/bhom_window_shell.py index a1ffc69..c271e6d 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/bhom_window_shell.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/bhom_window_shell.py @@ -141,6 +141,26 @@ def build(self): self.refresh_sizing() + def rebuild(self) -> None: + """Re-place all widgets so changes to `self.widgets` are reflected. + + Every BHoM widget currently managed by the content frame is removed from + its geometry manager (without being destroyed), then `build()` places the + widgets that are still in `self.widgets`. + """ + for child in self.content_frame.winfo_children(): + if not isinstance(child, BHoMBaseWidget): + continue + manager = child.winfo_manager() + if manager == "pack": + child.pack_forget() + elif manager == "grid": + child.grid_forget() + elif manager == "place": + child.place_forget() + + self.build() + def _set_window_icon(self) -> None: """Set a custom window icon, replacing Tk's default icon.""" icon_path = self.theme.icon_path diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/spinbox.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/spinbox.py index e29e29e..a19a621 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/spinbox.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/spinbox.py @@ -41,7 +41,9 @@ def __init__( super().__init__(parent, **kwargs) self.command = command - self._value_var = tk.StringVar() + # Bind to this widget's own interpreter: an unbound variable uses tkinter's default + # root, which can be a different (or stale) Tk instance once several roots exist. + self._value_var = tk.StringVar(master=self) # Store range/list constraints for validation self._from = from_ From 70356187948c25df2d38356e70fc97e37e209a5e Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Tue, 17 Nov 2026 11:52:33 +0000 Subject: [PATCH 7/8] colour blind suffixes added --- .../bhom_tkinter/widgets/cmap_selector.py | 49 ++++++++++++++----- .../src/python_toolkit/palettes/__init__.py | 2 + .../src/python_toolkit/palettes/registry.py | 12 +++++ .../Python/tests/test_colour_scale_builder.py | 8 +-- 4 files changed, 57 insertions(+), 14 deletions(-) diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index 3cce604..f7266fc 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py @@ -10,12 +10,15 @@ from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget from python_toolkit.bhom_tkinter.widgets._packing_options import PackingOptions -from python_toolkit.palettes import PaletteGroup, palette_names +from python_toolkit.palettes import PaletteGroup, is_colourblind_safe, palette_names from python_toolkit.colour_scales import ColourScale, ColourScaleError, delete_scale, finite_values, load_scales from python_toolkit.bhom.analytics import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.theming.scaling import scale_pad +# Shown after the name of a colour-blind safe palette in the dropdown; display only, never part of the name +COLOURBLIND_SAFE_TAG = " [colour blind safe]" + # Accepted colormap input types for colormaps parameter and set()/add_cmap() CmapInput = Union[str, Colormap, List[str]] @@ -43,6 +46,7 @@ def __init__( data: Optional[Iterable] = None, units: Optional[str] = None, scales_path: Optional[Path] = None, + show_tags: bool = True, **kwargs ) -> None: """ @@ -71,6 +75,8 @@ def __init__( histogram and break suggestions, and used to stretch the end bands. units: Units of `data`, stored with new scales. scales_path: Saved scales file (defaults to the user's saved scales). + show_tags: Show tags such as "[colour blind safe]" after palette names in the dropdown. Display only: + `get()`, `set()` and the palette names themselves never include the tag. **kwargs: Additional Frame options. """ super().__init__(parent, **kwargs) @@ -81,6 +87,9 @@ def __init__( self.data = None if data is None else finite_values(data) self.units = units self.scales_path = scales_path + self.show_tags = show_tags + self._names: List[str] = [] # the names behind the dropdown entries, in order + self._display_to_name: Dict[str, str] = {} self._scales: Dict[str, ColourScale] = {} # combobox label -> saved scale # Registry of custom (non-matplotlib-named) colormaps: label → Colormap @@ -90,7 +99,9 @@ def __init__( self.cmap_frame = ttk.Frame(self.content_frame) self.cmap_frame.pack(side="top", fill="both", expand=True, anchor=self._pack_anchor) - self.colormap_var = tk.StringVar(value="viridis") + self.colormap_var = tk.StringVar(master=self, value="viridis") # the selected name; the dropdown shows `cmap_display_var` + self.cmap_display_var = tk.StringVar(master=self) + self.colormap_var.trace_add("write", lambda *_: self.cmap_display_var.set(self._display_name(self.colormap_var.get()))) self._all_colormaps = palette_names() self._uses_explicit_colormaps = colormaps is not None @@ -102,7 +113,7 @@ def __init__( content.grid(row=0, column=0, padx=scale_pad(0), pady=scale_pad(4), sticky=self._grid_sticky) content.grid_propagate(False) - self.cmap_set_var = tk.StringVar(value=cmap_set.lower()) + self.cmap_set_var = tk.StringVar(master=self, value=cmap_set.lower()) pos = dropdown_position.lower() is_horizontal = pos in ("w", "e") @@ -117,7 +128,7 @@ def __init__( self.cmap_combobox = ttk.Combobox( header, - textvariable=self.colormap_var, + textvariable=self.cmap_display_var, state="readonly", justify=self._text_justify, ) @@ -146,7 +157,7 @@ def __init__( self._populate_cmap_list(current_colormaps) if include_scales: self._refresh_scales() - current_colormaps = list(self.cmap_combobox["values"]) + current_colormaps = list(self._names) # Resolve default_cmap: may itself be a Colormap object or colour list self._default_label = self._resolve_default_label(default_cmap, current_colormaps) @@ -269,9 +280,24 @@ def _resolve_default_label(self, default: Optional[CmapInput], available: List[s return None + def _display_name(self, name: str) -> str: + """The dropdown text for a name: the name, plus its tags when `show_tags` is on.""" + if self.show_tags and name not in self._custom_cmaps and is_colourblind_safe(name): + return f"{name}{COLOURBLIND_SAFE_TAG}" + return name + + @property + def cmap_names(self) -> List[str]: + """The names the dropdown offers, without display tags.""" + return list(self._names) + def _populate_cmap_list(self, colormaps: List[str]) -> None: """Replace the combobox options with the provided colormap names.""" - self.cmap_combobox["values"] = tuple(colormaps) + self._names = list(colormaps) + self._display_to_name = {self._display_name(name): name for name in self._names} + self.cmap_combobox["values"] = tuple(self._display_to_name) + self.cmap_combobox.configure(width=max([20, *(len(d) for d in self._display_to_name)]) + 1) # wide enough for the tags + self.cmap_display_var.set(self._display_name(self.colormap_var.get())) def _select_default_cmap(self, colormaps: List[str]) -> None: """Select an initial colormap and render its preview.""" @@ -286,6 +312,7 @@ def _select_default_cmap(self, colormaps: List[str]) -> None: def _on_cmap_selected(self, event=None) -> None: """Handle combobox selection changes.""" + self.colormap_var.set(self._display_to_name.get(self.cmap_display_var.get(), self.cmap_display_var.get())) self._update_cmap_sample() self._fire_on_change(self.get()) @@ -390,13 +417,13 @@ def _refresh_scales(self, select: Optional[str] = None) -> None: except ColourScaleError as e: # an unreadable file must not break the selector CONSOLE_LOGGER.warning(str(e)) scales = [] - palette_values = [v for v in self.cmap_combobox["values"] if v not in self._scales] + palette_values = [v for v in self._names if v not in self._scales] self._scales = {self._scale_label(s.name): s for s in scales} for label, scale in self._scales.items(): self._custom_cmaps[label] = scale.cmap_and_norm(self.data)[0] self._populate_cmap_list(palette_values + list(self._scales)) target = self._scale_label(select) if select else previous - if target in self.cmap_combobox["values"]: + if target in self._names: self.colormap_var.set(target) self._update_cmap_sample() elif previous: # the selected scale was deleted @@ -473,7 +500,7 @@ def add_cmap(self, cmap: CmapInput, label: Optional[str] = None) -> Optional[str Optional[str]: The display label used for the new entry, or `None` if the input was invalid or already present. """ - existing = list(self.cmap_combobox["values"]) + existing = list(self._names) if isinstance(cmap, str): if cmap not in self._all_colormaps or cmap in existing: @@ -525,7 +552,7 @@ def set(self, value: Optional[CmapInput]) -> None: value = self._scale_label(value.name) if isinstance(value, str): - if value in self.cmap_combobox["values"]: + if value in self._names: self.colormap_var.set(value) self._update_cmap_sample() else: @@ -568,7 +595,7 @@ def validate(self) -> tuple[bool, Optional[str], Optional[Literal['info', 'warni name = self.colormap_var.get() if not name: return self.apply_validation((False, "No colormap selected.", "error")) - if name not in self.cmap_combobox["values"]: + if name not in self._names: return self.apply_validation((False, f"Selected colormap '{name}' is not available.", "error")) return self.apply_validation((True, None, None)) diff --git a/Python_Engine/Python/src/python_toolkit/palettes/__init__.py b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py index 8cb74ef..f3dc9ef 100644 --- a/Python_Engine/Python/src/python_toolkit/palettes/__init__.py +++ b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py @@ -11,6 +11,7 @@ from python_toolkit.palettes.registry import ( PaletteGroup, is_categorical, + is_colourblind_safe, palette_names, register_toolkit_palettes, sample_colours, @@ -24,6 +25,7 @@ "PaletteGroup", "TOOLKIT_PALETTES", "is_categorical", + "is_colourblind_safe", "palette_names", "register_toolkit_palettes", "sample_colours", diff --git a/Python_Engine/Python/src/python_toolkit/palettes/registry.py b/Python_Engine/Python/src/python_toolkit/palettes/registry.py index 131804f..40ca4e3 100644 --- a/Python_Engine/Python/src/python_toolkit/palettes/registry.py +++ b/Python_Engine/Python/src/python_toolkit/palettes/registry.py @@ -64,6 +64,18 @@ def is_categorical(name: str) -> bool: return name.removesuffix("_r") in _group_members(PaletteGroup.CATEGORICAL) +def is_colourblind_safe(name: str) -> bool: + """Whether a palette, or its reversed copy, is tagged as colour-blind safe. + + Args: + name: Palette name. + + Returns: + bool: True if the palette is distinguishable with the common colour vision deficiencies. + """ + return name.removesuffix("_r") in _group_members(PaletteGroup.COLOURBLIND) + + def sample_colours(name: str, count: int) -> list[str]: """Pick colours from a palette. diff --git a/Python_Engine/Python/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py index 01947cc..1821d47 100644 --- a/Python_Engine/Python/tests/test_colour_scale_builder.py +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -118,14 +118,16 @@ def test_builder_starts_from_a_palette_and_recolours(host, library): def test_cmap_selector_lists_palette_sets(host): for cmap_set, expected in (("categorical", "okabe_ito"), ("colourblind", "okabe_ito"), ("continuous", "ltc_maya")): - values = list(CmapSelector(host.content_frame, cmap_set=cmap_set).cmap_combobox["values"]) + values = list(CmapSelector(host.content_frame, cmap_set=cmap_set).cmap_names) assert expected in values and f"{expected}_r" in values - assert "okabe_ito" not in CmapSelector(host.content_frame, cmap_set="continuous").cmap_combobox["values"] + assert "okabe_ito" not in CmapSelector(host.content_frame, cmap_set="continuous").cmap_names def test_cmap_selector_lists_what_it_is_given(host): selector = CmapSelector(host.content_frame, colormaps=["viridis"]) - assert list(selector.cmap_combobox["values"]) == ["viridis"] + assert selector.cmap_names == ["viridis"] + assert list(selector.cmap_combobox["values"]) == ["viridis [colour blind safe]"] # the tag is display only + assert selector.get() == "viridis" def test_end_to_end_palette_to_saved_scale_to_colours(host, library): From d6b0a5ea55a3bfb737337be038bdd314396341b3 Mon Sep 17 00:00:00 2001 From: Felix Mallinder Date: Wed, 18 Nov 2026 11:02:13 +0000 Subject: [PATCH 8/8] added label to the cmap selector in palletes tool --- .../bhom_tkinter/widgets/cmap_selector.py | 9 ++---- .../widgets/drop_down_selection.py | 29 ++++++++++++++++--- .../windows/colour_scale_builder.py | 4 +-- .../src/python_toolkit/palettes/__init__.py | 2 ++ .../src/python_toolkit/palettes/registry.py | 17 +++++++++++ 5 files changed, 49 insertions(+), 12 deletions(-) diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index f7266fc..ab3022e 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py @@ -10,15 +10,12 @@ from python_toolkit.bhom_tkinter.widgets.figure_container import FigureContainer from python_toolkit.bhom_tkinter.widgets._widgets_base import BHoMBaseWidget from python_toolkit.bhom_tkinter.widgets._packing_options import PackingOptions -from python_toolkit.palettes import PaletteGroup, is_colourblind_safe, palette_names +from python_toolkit.palettes import PaletteGroup, palette_label, palette_names from python_toolkit.colour_scales import ColourScale, ColourScaleError, delete_scale, finite_values, load_scales from python_toolkit.bhom.analytics import CONSOLE_LOGGER from python_toolkit.bhom_tkinter.theming.scaling import scale_pad -# Shown after the name of a colour-blind safe palette in the dropdown; display only, never part of the name -COLOURBLIND_SAFE_TAG = " [colour blind safe]" - # Accepted colormap input types for colormaps parameter and set()/add_cmap() CmapInput = Union[str, Colormap, List[str]] @@ -282,8 +279,8 @@ def _resolve_default_label(self, default: Optional[CmapInput], available: List[s def _display_name(self, name: str) -> str: """The dropdown text for a name: the name, plus its tags when `show_tags` is on.""" - if self.show_tags and name not in self._custom_cmaps and is_colourblind_safe(name): - return f"{name}{COLOURBLIND_SAFE_TAG}" + if self.show_tags and name not in self._custom_cmaps: + return palette_label(name) return name @property diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py index 47b6083..35a68b7 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py @@ -19,6 +19,7 @@ def __init__( width: int = 20, state: str = "normal", value_var: Optional[tk.StringVar] = None, + display: Optional[Callable[[str], str]] = None, **kwargs): """ Args: @@ -28,6 +29,8 @@ def __init__( default (str, optional): Default selected value. width (int): Width of the dropdown widget in characters. state (str): Combobox state ("normal", "readonly", or "disabled"). + display (callable, optional): Maps an option to the text the dropdown shows for it. Display only: + `get()`, `set()` and `command` always use the plain option. item_title (str, optional): Optional header text shown at the top of the widget frame. helper_text (str, optional): Optional helper text shown above the dropdown. **kwargs: Additional Frame options. @@ -36,13 +39,19 @@ def __init__( self.options = [str(option) for option in (options or [])] self.command = command - self.value_var = value_var or tk.StringVar() + self.value_var = value_var or tk.StringVar(master=self) + self._display = display + self._display_to_option = {} + # With a display function the combobox shows its own text variable, kept in step with `value_var` + self._shown_var = tk.StringVar(master=self) if display else self.value_var + if display: + self.value_var.trace_add("write", lambda *_: self._shown_var.set(self._shown(self.value_var.get()))) # Create the combobox in the content frame self.combobox = ttk.Combobox( self.content_frame, - textvariable=self.value_var, - values=self.options, + textvariable=self._shown_var, + values=self._shown_options(), width=width, state=state, justify=self._text_justify, @@ -58,12 +67,24 @@ def __init__( elif self.options: self.value_var.set(self.options[0]) + def _shown(self, option: str) -> str: + """The text the dropdown shows for an option.""" + return self._display(option) if self._display and option in self.options else option + + def _shown_options(self) -> List[str]: + """The dropdown entries: the options as shown, remembering which option each one is.""" + self._display_to_option = {self._shown(option): option for option in self.options} + return list(self._display_to_option) if self._display else list(self.options) + def _on_select(self, event=None): """Handle selection change event. Args: event: Tkinter event (optional). """ + if self._display: + shown = self._shown_var.get() + self.value_var.set(self._display_to_option.get(shown, shown)) if self.command: self.command(self.get()) self._fire_on_change(self.get()) @@ -95,7 +116,7 @@ def set_options(self, options: List[str], default: Optional[str] = None): default: Optional value to select after updating options. """ self.options = [str(option) for option in (options or [])] - self.combobox['values'] = self.options + self.combobox['values'] = self._shown_options() if default is not None and default in self.options: self.set(default) diff --git a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py index 758f238..1f09c41 100644 --- a/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -38,7 +38,7 @@ save_scale, suggest_thresholds, ) -from python_toolkit.palettes import palette_names, sample_colours +from python_toolkit.palettes import palette_label, palette_names, sample_colours from python_toolkit.plot.colour_scale_histogram import colour_scale_histogram MAX_BANDS = 24 @@ -157,7 +157,7 @@ def _build_controls(self, parent: ttk.Frame, row: int) -> None: options = palette_names() self.palette = DropDownSelection(controls, id="palette", helper_text="Palette / colour map", options=options, default=self._start_palette if self._start_palette in options else "viridis", - state="readonly", width=6, command=lambda _v: self._recolour(), + state="readonly", width=6, command=lambda _v: self._recolour(), display=palette_label, build_options=GridOptions(row=0, column=2, sticky="ew")) for widget in (self.band_count, self.method, self.palette): widget.build() diff --git a/Python_Engine/Python/src/python_toolkit/palettes/__init__.py b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py index f3dc9ef..c50cda6 100644 --- a/Python_Engine/Python/src/python_toolkit/palettes/__init__.py +++ b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py @@ -12,6 +12,7 @@ PaletteGroup, is_categorical, is_colourblind_safe, + palette_label, palette_names, register_toolkit_palettes, sample_colours, @@ -26,6 +27,7 @@ "TOOLKIT_PALETTES", "is_categorical", "is_colourblind_safe", + "palette_label", "palette_names", "register_toolkit_palettes", "sample_colours", diff --git a/Python_Engine/Python/src/python_toolkit/palettes/registry.py b/Python_Engine/Python/src/python_toolkit/palettes/registry.py index 40ca4e3..ed7f3ab 100644 --- a/Python_Engine/Python/src/python_toolkit/palettes/registry.py +++ b/Python_Engine/Python/src/python_toolkit/palettes/registry.py @@ -76,6 +76,23 @@ def is_colourblind_safe(name: str) -> bool: return name.removesuffix("_r") in _group_members(PaletteGroup.COLOURBLIND) +COLOURBLIND_SAFE_TAG = " [colour blind safe]" + + +def palette_label(name: str) -> str: + """The text to show for a palette in a list: its name, plus a tag where one applies. + + The tag is for display only and is never part of the palette's name. + + Args: + name: Palette name. + + Returns: + str: The name, followed by " [colour blind safe]" for a colour-blind safe palette. + """ + return f"{name}{COLOURBLIND_SAFE_TAG}" if is_colourblind_safe(name) else name + + def sample_colours(name: str, count: int) -> list[str]: """Pick colours from a palette.