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/cmap_selector.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/cmap_selector.py index 4d53594..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 @@ -1,14 +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.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 @@ -27,48 +30,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, @@ -78,6 +39,11 @@ 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, + show_tags: bool = True, **kwargs ) -> None: """ @@ -90,7 +56,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.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`. @@ -98,12 +65,29 @@ 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.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). + 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) self.cmap_bins = cmap_bins self.plot_size = plot_size + self.include_scales = include_scales + 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 self._custom_cmaps: Dict[str, Colormap] = {} @@ -112,23 +96,21 @@ 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._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.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 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) - 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") @@ -143,12 +125,15 @@ def __init__( self.cmap_combobox = ttk.Combobox( header, - textvariable=self.colormap_var, + textvariable=self.cmap_display_var, state="readonly", justify=self._text_justify, ) 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( @@ -167,40 +152,14 @@ 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._names) # 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) - 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. @@ -231,7 +190,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(self._preset_map.get(key, self._preset_map["all"])) + 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. @@ -317,9 +277,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: + return palette_label(name) + 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.""" @@ -334,6 +309,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()) @@ -404,6 +380,107 @@ def get_cmap(self) -> Optional[Colormap]: return mpl.colormaps.get(name) + # ── saved colour scales ──────────────────────────────────────────────── + + @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)) + 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: + """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) + + 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._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._names: + 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 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 + 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]: + """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]: + """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. + + Returns: + Optional[BoundaryNorm]: The normaliser, or None when a plain palette is selected. + """ + scale = self.get_scale() + 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. @@ -420,7 +497,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: @@ -468,8 +545,11 @@ 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"]: + if value in self._names: self.colormap_var.set(value) self._update_cmap_sample() else: @@ -512,7 +592,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)) @@ -599,6 +679,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/widgets/drop_down_selection.py b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/widgets/drop_down_selection.py index f5afb4d..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 @@ -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): @@ -18,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: @@ -27,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. @@ -35,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, @@ -57,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()) @@ -94,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/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_ 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..1f09c41 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/bhom_tkinter/windows/colour_scale_builder.py @@ -0,0 +1,489 @@ +"""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 to the saved scales file +(see ``python_toolkit.colour_scales``):: + + builder = ColourScaleBuilder(parent, data=room_temperatures, units="degC") + builder.run() + scale = builder.saved_scale # None if closed without saving +""" + +import math +import tkinter as tk +from dataclasses import dataclass +from pathlib import Path +from tkinter import ttk +from typing import Callable, Iterable, Optional, Sequence + +import numpy as np + +from python_toolkit.bhom.logging import CONSOLE_LOGGER +from python_toolkit.bhom_tkinter.bhom_base_child_window import BHoMBaseChildWindow +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 +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.spinbox import Spinbox +from python_toolkit.bhom_tkinter.widgets.validated_entry_box import ValidatedEntryBox +from python_toolkit.bhom_tkinter.windows.warning_box import WarningBox +from python_toolkit.colour_scales import ( + BreakMethod, + ColourScale, + ColourScaleError, + finite_values, + load_scales, + save_scale, + suggest_thresholds, +) +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 +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" + +Bands = tuple[list[float], list[str], list[Optional[str]]] # thresholds, colours, labels + + +@dataclass +class BandRow: + """The widgets of one row of the band table.""" + + 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): + """Build, preview and save a ColourScale against real data.""" + + def __init__( + self, + parent: Optional[tk.Misc] = None, + data: Optional[Iterable] = None, + units: Optional[str] = None, + scale: Optional[ColourScale] = None, + library_path: Optional[Path] = None, + on_save: Optional[Callable[[ColourScale], None]] = None, + palette: Optional[str] = None, + **kwargs, + ) -> None: + """ + 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_path: File to save into (defaults to the user's saved scales). + on_save: Called with the saved scale. + palette: Palette to start from (e.g. the plot's current one). + **kwargs: Additional BHoMBaseChildWindow options. + """ + 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[BandRow] = [] + self._preview_job: Optional[str] = None + self._suggest_job: Optional[str] = None + self._syncing = False + 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", 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: + """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 = _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._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] + + 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._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=[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 = 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(), display=palette_label, + build_options=GridOptions(row=0, column=2, sticky="ew")) + for widget in (self.band_count, self.method, self.palette): + widget.build() + 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") + + 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, 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 {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._show_bands(scale.thresholds, scale.colours(), scale.labels) + else: + self.name.set(self._unused_name("New scale")) + 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 _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_scheduled_suggestion) + + 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()) + except ValueError: # half-typed count + return + if 2 <= bands <= MAX_BANDS: + self._suggest() + + def _suggest(self) -> None: + """Replace the thresholds with suggested ones, keeping hand-picked colours and labels where bands remain.""" + try: + thresholds = suggest_thresholds(self.values, int(self.band_count.get()), self.method.get()) + except (ColourScaleError, ValueError) as error: + self.status.set(str(error)) + return + 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 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 error: + self.status.set(str(error)) + return + if len(colours) >= MAX_BANDS: + return + 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 + hand_coloured = self._is_hand_coloured(colours) + thresholds.insert(index, middle) + colours.insert(index + 1, colours[index]) + labels.insert(index + 1, None) + 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 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 error: + self.status.set(str(error)) + return + count = len(colours) + if count <= 2: + return + hand_coloured = self._is_hand_coloured(colours) + thresholds.pop(min(index, count - 2)) + colours.pop(index) + labels.pop(index) + self._show_edited_bands(thresholds, colours, labels, hand_coloured) + + 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: + """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, sample_colours(self.palette.get(), len(self._band_rows))): + row.colour.set(colour) + self._schedule_preview() + + 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() + 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(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 _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() + 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 thresholds, colours, labels + + def current_scale(self) -> ColourScale: + """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() + 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: + 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: + """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 error: + self._show_save_error(str(error)) + return + CONSOLE_LOGGER.info(f"Saved colour scale '{scale.name}'.") + self.saved_scale = scale + if self.on_save is not 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: + """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._preview_job) + except tk.TclError: + pass + self._preview_job = self.after(delay, self._update_preview) + + def _update_preview(self) -> 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 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}") + style = ttk.Style() + 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__": + 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/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..c50cda6 --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/palettes/__init__.py @@ -0,0 +1,34 @@ +"""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, + is_colourblind_safe, + palette_label, + 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", + "is_colourblind_safe", + "palette_label", + "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..ed7f3ab --- /dev/null +++ b/Python_Engine/Python/src/python_toolkit/palettes/registry.py @@ -0,0 +1,121 @@ +"""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 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) + + +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. + + 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/tests/test_colour_scale_builder.py b/Python_Engine/Python/tests/test_colour_scale_builder.py new file mode 100644 index 0000000..1821d47 --- /dev/null +++ b/Python_Engine/Python/tests/test_colour_scale_builder.py @@ -0,0 +1,338 @@ +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.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") +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 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_path=library) + scale = builder.current_scale() + 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() + + +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._save() + scale = load_scales(library)[0] + assert saved and saved[0].name == "Comfort" + 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_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 load_scales(library) == [] + + +def test_builder_name_clash_is_explained_and_default_names_are_free(host, library, warnings_shown): + 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() + 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_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 = ColourScale("T", [20, 25], ["#0000ff", "#00ff00", "#ff0000"]) + 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] == 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") + assert builder.current_scale().cmap[0] == "#123456" # a hand-picked colour makes it an explicit list + + +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_names) + assert expected in values and f"{expected}_r" in 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 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): + """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, 25, 27.5]) + cmap, norm = scale.cmap_and_norm() + colours = {to_hex(cmap(norm(v))) for v in data} + 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() == 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_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_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 + + +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_scheduled_suggestion() + assert len(builder._band_rows) == 12 + builder.band_count.set("99") # out of range: ignored, bands stay as they are + builder._run_scheduled_suggestion() + 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_scheduled_suggestion() + scale = builder.current_scale() + 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_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] == 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_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 + 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 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, 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 + + +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) # 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): + 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, 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, 25]) 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_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_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._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 new file mode 100644 index 0000000..3d7cd58 --- /dev/null +++ b/Python_Engine/Python/tests/test_colour_scales.py @@ -0,0 +1,227 @@ +import json + +import numpy as np +import pytest +from matplotlib import colormaps +from matplotlib.colors import to_hex + +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.cmap_and_norm() + return to_hex(cmap(norm(value))) + + +# -- palettes ------------------------------------------------------------------ + +def test_toolkit_palettes_are_always_registered(): + 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 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(): + # 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 ---------------- + +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_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_changing_the_palette_keeps_the_breaks(): + scale = ColourScale("Heat", [10, 20, 30], "viridis") + assert scale.colours() == sample_colours("viridis", 4) + scale.cmap = "okabe_ito" + 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"): + scale.cmap = ["red", "green"] + + +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_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] + 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", [ + ([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") + assert thresholds == pytest.approx(expected) + assert all(min(data) < t < max(data) for t in thresholds) + + +# -- 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() + + +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"): + 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_are_skipped_and_kept(tmp_path): + path = tmp_path / "mixed.json" + path.write_text(json.dumps({"scales": [ + ColourScale("Good", [1], "viridis").to_dict(), + {"name": "Broken", "thresholds": [2, 1], "cmap": "viridis"}, + ]}), encoding="utf-8") + 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_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_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) + + +@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 + + +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): + 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"] + + +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")