bsplot 0.0.2__py3-none-any.whl

bsplot/colors.py

@@ -0,0 +1,1935 @@
+import json
+import os
+import re
+
+import matplotlib as mpl
+import matplotlib.colors as mcolors
+import matplotlib.pyplot as plt
+import pandas as pd
+import yaml
+from matplotlib.colors import rgb2hex
+
+# from pybtex.database import Entry
+import numpy as np
+import matplotlib.cm as cm
+from cycler import cycler
+
+try:
+    import cmap as cmap_lib
+    HAS_CMAP = True
+except ImportError:
+    HAS_CMAP = False
+
+
+class Palette:
+    """
+    A color palette class for managing discrete sets of colors.
+
+    Use `Palette.list_available()` to see built-in palettes and
+    `Palette.load(name)` to load them.
+    """
+
+    # Registry of built-in palettes
+    _registry = {}
+
+    def __init__(self, colors=None, reference=None, **kwargs):
+        """
+        Initialize the palette with an optional dictionary of colors.
+
+        Parameters:
+            colors (dict): Optional dictionary of colors where each key is a color name,
+                           and each value is either a HEX string or an RGB tuple.
+        """
+        self.colors = {}
+
+        if "name" in kwargs:
+            self.name = kwargs.pop("name")
+        else:
+            self.name = "Custom Palette"
+
+        if colors is not None:
+
+            if isinstance(colors, dict):
+                for name, color in colors.items():
+                    if isinstance(color, tuple) and len(color) == 3:
+                        self.add_color(name, rgb=color)
+                    elif isinstance(color, str) and color.startswith("#"):
+                        self.add_color(name, hex_code=color)
+                    else:
+                        raise ValueError(
+                            "Colors must be in RGB tuple or HEX string format."
+                        )
+            else:
+                for color in colors:
+                    if len(color) == 3:
+                        self.add_color(f"color_{len(self.colors) + 1}", rgb=color)
+                    elif isinstance(color, str) and color.startswith("#"):
+                        self.add_color(f"color_{len(self.colors) + 1}", hex_code=color)
+                    else:
+                        raise ValueError(
+                            "Colors must be in RGB tuple or HEX string format."
+                        )
+
+        if reference:
+            self.reference = reference
+
+    def __repr__(self):
+        return f"Palette('{self.name}', {len(self.colors)} colors)"
+
+    @classmethod
+    def register(cls, name, palette):
+        """Register a palette in the registry."""
+        cls._registry[name] = palette
+        palette.name = name
+        return palette
+
+    @classmethod
+    def list_available(cls):
+        """
+        List all available built-in palettes.
+
+        Returns:
+            list: List of palette names.
+        """
+        return list(cls._registry.keys())
+
+    @classmethod
+    def load(cls, name):
+        """
+        Load a palette by name.
+
+        Parameters:
+            name (str): Name of the palette.
+
+        Returns:
+            Palette: The requested palette.
+
+        Raises:
+            ValueError: If palette not found.
+        """
+        if name not in cls._registry:
+            available = cls.list_available()
+            raise ValueError(
+                f"Palette '{name}' not found. Available: {', '.join(available)}"
+            )
+        return cls._registry[name]
+
+    @classmethod
+    def from_cmap(cls, cmap, n=8, start=0.0, stop=1.0, name=None):
+        """
+        Create a Palette by sampling colors from a colormap.
+
+        Parameters:
+            cmap: Colormap name (str) or colormap instance.
+            n (int): Number of colors to sample.
+            start (float): Start of sampling range [0, 1].
+            stop (float): End of sampling range [0, 1].
+            name (str): Optional name for the palette.
+
+        Returns:
+            Palette: A new Palette with sampled colors.
+
+        Example:
+            >>> palette = Palette.from_cmap('viridis', n=5)
+            >>> palette = Palette.from_cmap('batlow', n=8)  # scientific cmap
+        """
+        # Get the colormap (Colormap handles str -> cmap conversion)
+        if isinstance(cmap, str):
+            cmap_obj = Colormap(cmap)
+            cmap_name = cmap
+        else:
+            cmap_obj = cmap
+            cmap_name = getattr(cmap, "name", "custom")
+
+        # Sample colors
+        t = np.linspace(start, stop, n)
+        sampled_colors = {}
+        for i, val in enumerate(t):
+            rgba = cmap_obj(val)
+            hex_color = mcolors.to_hex(rgba)
+            sampled_colors[f"color_{i + 1}"] = hex_color
+
+        palette_name = name or f"{cmap_name}_{n}"
+        return cls(sampled_colors, name=palette_name)
+
+    def add_color(self, name, rgb=None, hex_code=None):
+        """
+        Add a color to the palette.
+
+        Parameters:
+            name (str): Name of the color.
+            rgb (tuple): RGB tuple (R, G, B) with values from 0 to 255.
+            hex_code (str): HEX color code as a string (e.g., '#FF5733').
+        """
+        if rgb is not None:
+            if max(rgb) > 1:
+                rgb = tuple(value / 255 for value in rgb)
+            hex_color = rgb2hex(rgb)
+        elif hex_code is not None:
+            hex_color = hex_code
+            rgb = tuple(int(hex_code[i : i + 2], 16) for i in (1, 3, 5))
+        else:
+            raise ValueError("Either rgb or hex_code must be provided.")
+
+        self.colors[name] = {"rgb": rgb, "hex": hex_color}
+
+    def get_color(self, name):
+        """
+        Retrieve a color from the palette by name.
+
+        Parameters:
+            name (str): Name of the color.
+
+        Returns:
+            dict: A dictionary with RGB and HEX values of the color.
+        """
+        return self.colors.get(name, None)
+
+    def get_hex_colors(self):
+        """
+        Get a list of all colors in HEX format.
+
+        Returns:
+            list: List of HEX color codes as strings.
+        """
+        return [color["hex"] for color in self.colors.values()]
+
+    def get_rgb_colors(self):
+        """
+        Get a list of all colors in RGB format.
+
+        Returns:
+            list: List of RGB color tuples.
+        """
+        return [color["rgb"] for color in self.colors.values()]
+
+    def to_json(self, file_path=None):
+        """
+        Export the palette as JSON.
+
+        Parameters:
+            file_path (str): Optional path to save the JSON file.
+
+        Returns:
+            str: JSON string if file_path is None, otherwise saves JSON to file.
+        """
+        if file_path:
+            with open(file_path, "w") as f:
+                json.dump(self.colors, f, indent=4)
+        return json.dumps(self.colors, indent=4)
+
+    def to_yaml(self, file_path=None):
+        """
+        Export the palette as YAML.
+
+        Parameters:
+            file_path (str): Optional path to save the YAML file.
+
+        Returns:
+            str: YAML string if file_path is None, otherwise saves YAML to file.
+        """
+        if file_path:
+            with open(file_path, "w") as f:
+                yaml.dump(self.colors, f)
+        return yaml.dump(self.colors)
+
+    def to_css(self, file_path=None):
+        """
+        Export the palette as a CSS custom properties file.
+
+        Parameters:
+            file_path (str): Optional path to save the CSS file.
+
+        Returns:
+            str: CSS string if file_path is None, otherwise saves CSS to file.
+        """
+        css = ":root {\n"
+        for name, color in self.colors.items():
+            css += f"  --{name.lower().replace(' ', '-')}: {color['hex']};\n"
+        css += "}"
+
+        if file_path:
+            with open(file_path, "w") as f:
+                f.write(css)
+        return css
+
+    def plot(self):
+        """
+        Display a bar plot of the colors in the palette.
+        """
+        hex_colors = self.get_hex_colors()
+        color_names = list(self.colors.keys())
+
+        fig, ax = plt.subplots(figsize=(len(hex_colors), 1))
+        ax.imshow([hex_colors], aspect="auto", extent=[0, len(hex_colors), 0, 1])
+        ax.set_yticks([])
+
+        # Add color labels below each color bar
+        ax.set_xticks(range(len(hex_colors)))
+        ax.set_xticklabels(color_names, rotation=45, ha="right")
+
+        plt.tight_layout()
+        plt.show()
+
+    def update_rc_params(self):
+        """
+        Update matplotlib's rcParams using the palette colors.
+        Sets the color cycle and other relevant properties.
+        """
+        hex_colors = self.get_hex_colors()
+
+        # Update color cycle and other rcParams with available colors
+        mpl.rcParams["axes.prop_cycle"] = mpl.cycler("color", hex_colors)
+
+    def create_sequential_colormaps(self, base_color="#FFFFFF"):
+        """
+        Create sequential colormaps from white to each color in the palette.
+
+        Returns:
+            dict: A dictionary where keys are color names and values are
+                LinearSegmentedColormap instances transitioning from white
+                to the respective color.
+        """
+        colormaps = {}
+
+        for name, color in self.colors.items():
+            # Create a colormap that transitions from white to the color
+            cmap = mcolors.LinearSegmentedColormap.from_list(
+                f"{name}_sequential", [base_color, color["hex"]]
+            )
+            colormaps[name] = cmap
+
+        return colormaps
+
+    def create_colormap(self, type="linear"):
+        """
+        Create a colormap from the palette colors.
+
+        Returns:
+            LinearSegmentedColormap: A colormap transitioning between the colors in the palette.
+        """
+
+        # Create a colormap that transitions between the colors in the palette
+        colors = [color["hex"] for color in self.colors.values()]
+        if type == "linear":
+            cmap = mcolors.LinearSegmentedColormap.from_list("custom", colors)
+        if type == "listed":
+            cmap = mcolors.ListedColormap(colors)
+        cmap.name = self.name
+        return cmap
+
+    def get_cmap(self, type="linear"):
+        return self.create_colormap(type=type)
+
+    @property
+    def hex(self):
+        """Get HEX colors as a property."""
+        return self.get_hex_colors()
+
+    @property
+    def rgb(self):
+        """Get RGB colors as a property."""
+        return self.get_rgb_colors()
+
+
+# Register built-in palettes
+
+# Wong (2011) colorblind-safe palette - Nature Methods
+Palette.register(
+    "colorblind",
+    Palette(
+        {
+            "Black": (0, 0, 0),
+            "Orange": (230, 159, 0),
+            "Sky Blue": (86, 180, 233),
+            "Bluish Green": (0, 158, 115),
+            "Yellow": (240, 228, 66),
+            "Blue": (0, 114, 178),
+            "Vermillion": (213, 94, 0),
+            "Reddish Purple": (204, 121, 167),
+        },
+    ),
+)
+
+# NPG (Nature Publishing Group) from ggsci
+Palette.register(
+    "npg",
+    Palette(
+        {
+            "Red": "#E64B35",
+            "Blue": "#4DBBD5",
+            "Green": "#00A087",
+            "Dark Blue": "#3C5488",
+            "Peach": "#F39B7F",
+            "Lavender": "#8491B4",
+            "Teal": "#91D1C2",
+            "Crimson": "#DC0000",
+            "Brown": "#7E6148",
+        },
+    ),
+)
+
+# Lancet from ggsci
+Palette.register(
+    "lancet",
+    Palette(
+        {
+            "Dark Blue": "#00468B",
+            "Light Blue": "#42B540",
+            "Orange": "#ED1C24",
+            "Cyan": "#0099B4",
+            "Brown": "#925E9F",
+            "Red": "#FDAF91",
+            "Gray": "#AD002A",
+            "Teal": "#ADB6B6",
+            "Black": "#1B1919",
+        },
+    ),
+)
+
+# JAMA from ggsci
+Palette.register(
+    "jama",
+    Palette(
+        {
+            "Dark Blue": "#374E55",
+            "Red": "#DF8F44",
+            "Teal": "#00A1D5",
+            "Brown": "#B24745",
+            "Gray": "#79AF97",
+            "Light": "#6A6599",
+            "Coral": "#80796B",
+        },
+    ),
+)
+
+# Okabe-Ito colorblind-safe (alternative name)
+Palette.register(
+    "okabe_ito",
+    Palette(
+        {
+            "Orange": "#E69F00",
+            "Sky Blue": "#56B4E9",
+            "Bluish Green": "#009E73",
+            "Yellow": "#F0E442",
+            "Blue": "#0072B2",
+            "Vermillion": "#D55E00",
+            "Reddish Purple": "#CC79A7",
+            "Black": "#000000",
+        },
+    ),
+)
+
+# Paul Tol's qualitative palette (muted)
+Palette.register(
+    "tol_muted",
+    Palette(
+        {
+            "Indigo": "#332288",
+            "Cyan": "#88CCEE",
+            "Teal": "#44AA99",
+            "Green": "#117733",
+            "Olive": "#999933",
+            "Sand": "#DDCC77",
+            "Rose": "#CC6677",
+            "Wine": "#882255",
+            "Purple": "#AA4499",
+        },
+    ),
+)
+
+# Paul Tol's bright palette
+Palette.register(
+    "tol_bright",
+    Palette(
+        {
+            "Blue": "#4477AA",
+            "Cyan": "#66CCEE",
+            "Green": "#228833",
+            "Yellow": "#CCBB44",
+            "Red": "#EE6677",
+            "Purple": "#AA3377",
+            "Grey": "#BBBBBB",
+        },
+    ),
+)
+
+# Paul Tol's vibrant palette
+Palette.register(
+    "tol_vibrant",
+    Palette(
+        {
+            "Orange": "#EE7733",
+            "Blue": "#0077BB",
+            "Cyan": "#33BBEE",
+            "Magenta": "#EE3377",
+            "Red": "#CC3311",
+            "Teal": "#009988",
+            "Grey": "#BBBBBB",
+        },
+    ),
+)
+
+# Tableau 10
+Palette.register(
+    "tableau10",
+    Palette(
+        {
+            "Blue": "#4E79A7",
+            "Orange": "#F28E2B",
+            "Red": "#E15759",
+            "Teal": "#76B7B2",
+            "Green": "#59A14F",
+            "Yellow": "#EDC948",
+            "Purple": "#B07AA1",
+            "Pink": "#FF9DA7",
+            "Brown": "#9C755F",
+            "Gray": "#BAB0AC",
+        },
+    ),
+)
+
+# Seaborn deep
+Palette.register(
+    "seaborn_deep",
+    Palette(
+        {
+            "Blue": "#4C72B0",
+            "Orange": "#DD8452",
+            "Green": "#55A868",
+            "Red": "#C44E52",
+            "Purple": "#8172B3",
+            "Brown": "#937860",
+            "Pink": "#DA8BC3",
+            "Gray": "#8C8C8C",
+            "Yellow": "#CCB974",
+            "Cyan": "#64B5CD",
+        },
+    ),
+)
+
+# Seaborn colorblind
+Palette.register(
+    "seaborn_colorblind",
+    Palette(
+        {
+            "Blue": "#0173B2",
+            "Orange": "#DE8F05",
+            "Green": "#029E73",
+            "Red": "#D55E00",
+            "Purple": "#CC78BC",
+            "Brown": "#CA9161",
+            "Pink": "#FBAFE4",
+            "Gray": "#949494",
+            "Yellow": "#ECE133",
+            "Cyan": "#56B4E9",
+        },
+    ),
+)
+
+# Set1 from ColorBrewer
+Palette.register(
+    "set1",
+    Palette(
+        {
+            "Red": "#E41A1C",
+            "Blue": "#377EB8",
+            "Green": "#4DAF4A",
+            "Purple": "#984EA3",
+            "Orange": "#FF7F00",
+            "Yellow": "#FFFF33",
+            "Brown": "#A65628",
+            "Pink": "#F781BF",
+            "Gray": "#999999",
+        },
+    ),
+)
+
+# Set2 from ColorBrewer
+Palette.register(
+    "set2",
+    Palette(
+        {
+            "Teal": "#66C2A5",
+            "Orange": "#FC8D62",
+            "Purple": "#8DA0CB",
+            "Pink": "#E78AC3",
+            "Green": "#A6D854",
+            "Yellow": "#FFD92F",
+            "Brown": "#E5C494",
+            "Gray": "#B3B3B3",
+        },
+    ),
+)
+
+# Dark2 from ColorBrewer
+Palette.register(
+    "dark2",
+    Palette(
+        {
+            "Teal": "#1B9E77",
+            "Orange": "#D95F02",
+            "Purple": "#7570B3",
+            "Pink": "#E7298A",
+            "Green": "#66A61E",
+            "Yellow": "#E6AB02",
+            "Brown": "#A6761D",
+            "Gray": "#666666",
+        },
+    ),
+)
+
+# Paired from ColorBrewer (good for paired comparisons)
+Palette.register(
+    "paired",
+    Palette(
+        {
+            "Light Blue": "#A6CEE3",
+            "Blue": "#1F78B4",
+            "Light Green": "#B2DF8A",
+            "Green": "#33A02C",
+            "Light Pink": "#FB9A99",
+            "Red": "#E31A1C",
+            "Light Orange": "#FDBF6F",
+            "Orange": "#FF7F00",
+            "Light Purple": "#CAB2D6",
+            "Purple": "#6A3D9A",
+        },
+    ),
+)
+
+# Register aliases for backward compatibility
+Palette._registry["ggsci"] = Palette._registry["npg"]  # ggsci is an alias for npg
+
+# Backward compatibility aliases
+colorblind_palette = Palette.load("colorblind")
+ggsci_palette = Palette.load("ggsci")
+
+
+class _ColormapMixin:
+    """
+    Mixin providing additional methods for colormaps.
+
+    This mixin adds intuitive methods for sampling, reversing, and converting
+    colormaps that work with both continuous and discrete colormaps.
+    """
+
+    def sample(self, n=5, start=0.0, stop=1.0, as_hex=False):
+        """
+        Sample n colors from this colormap.
+
+        Parameters:
+            n (int): Number of colors to sample.
+            start (float): Start of sampling range [0, 1].
+            stop (float): End of sampling range [0, 1].
+            as_hex (bool): If True, return hex strings instead of RGBA tuples.
+
+        Returns:
+            list: List of colors (RGBA tuples or hex strings).
+
+        Example:
+            >>> cmap = Colormap("viridis")
+            >>> cmap.sample(5, as_hex=True)
+            ['#440154', '#3b528b', '#21918c', '#5ec962', '#fde725']
+        """
+        t = np.linspace(start, stop, n)
+        colors = [self(v) for v in t]
+        if as_hex:
+            colors = [mcolors.to_hex(c) for c in colors]
+        return colors
+
+    def to_palette(self, n=8, start=0.0, stop=1.0, name=None):
+        """
+        Convert this colormap to a Palette by sampling colors.
+
+        Parameters:
+            n (int): Number of colors to sample.
+            start (float): Start of sampling range [0, 1].
+            stop (float): End of sampling range [0, 1].
+            name (str): Optional name for the palette.
+
+        Returns:
+            Palette: A new Palette instance with sampled colors.
+
+        Example:
+            >>> cmap = Colormap("batlow")
+            >>> palette = cmap.to_palette(n=6)
+        """
+        hex_colors = self.sample(n=n, start=start, stop=stop, as_hex=True)
+        palette_name = name or f"{self.name}_{n}"
+        return Palette(hex_colors, name=palette_name)
+
+    def truncate(self, start=0.0, stop=1.0, N=256, name=None):
+        """
+        Create a new colormap from a subset of this colormap's range.
+
+        Parameters:
+            start (float): Start of the range [0, 1].
+            stop (float): End of the range [0, 1].
+            N (int): Number of quantization levels.
+            name (str): Optional name for the new colormap.
+
+        Returns:
+            ContinuousColormap: A new colormap covering the specified range.
+
+        Example:
+            >>> cmap = Colormap("viridis")
+            >>> truncated = cmap.truncate(0.2, 0.8)
+        """
+        colors = self.sample(n=N, start=start, stop=stop)
+        cmap_name = name or f"{self.name}_truncated"
+        return ContinuousColormap.from_list(cmap_name, colors, N=N)
+
+    # ------------------------------------------------------------------
+    # Color-vision analysis helpers
+    # ------------------------------------------------------------------
+
+    # Vienot (1999) / Brettel (1997) colorblind simulation matrices.
+    # Applied in linear RGB space (after sRGB gamma removal).
+    _CVD_MATRICES = {
+        "protanopia": np.array([
+            [0.152286, 1.052583, -0.204868],
+            [0.114503, 0.786281, 0.099216],
+            [-0.003882, -0.048116, 1.051998],
+        ]),
+        "deuteranopia": np.array([
+            [0.367322, 0.860646, -0.227968],
+            [0.280085, 0.672501, 0.047414],
+            [-0.011820, 0.042940, 0.968881],
+        ]),
+        "tritanopia": np.array([
+            [1.255528, -0.076749, -0.178779],
+            [-0.078411, 0.930809, 0.147602],
+            [0.004733, 0.691367, 0.303900],
+        ]),
+    }
+
+    @staticmethod
+    def _srgb_to_linear(c):
+        """Convert sRGB [0-1] to linear RGB."""
+        c = np.asarray(c, dtype=float)
+        return np.where(c <= 0.04045, c / 12.92,
+                        ((c + 0.055) / 1.055) ** 2.4)
+
+    @staticmethod
+    def _linear_to_srgb(c):
+        """Convert linear RGB to sRGB [0-1]."""
+        c = np.asarray(c, dtype=float)
+        return np.where(c <= 0.0031308, 12.92 * c,
+                        1.055 * np.power(np.clip(c, 0, None), 1.0 / 2.4) - 0.055)
+
+    def _sample_rgba(self, N=256):
+        """Sample the colormap into an (N, 4) RGBA array."""
+        t = np.linspace(0, 1, N)
+        return np.array([self(v) for v in t])
+
+    def to_grayscale(self, N=256, name=None):
+        """
+        Create a grayscale version of this colormap using perceptual luminance.
+
+        Uses the Rec. 709 luminance weights (0.2126 R + 0.7152 G + 0.0722 B)
+        applied in linear RGB space for accurate perceptual conversion.
+
+        Parameters:
+            N (int): Number of quantization levels.
+            name (str): Name for the new colormap.
+
+        Returns:
+            ContinuousColormap: A grayscale version of this colormap.
+
+        Example:
+            >>> cmap = Colormap("viridis")
+            >>> gray = cmap.to_grayscale()
+        """
+        rgba = self._sample_rgba(N)
+        rgb_linear = self._srgb_to_linear(rgba[:, :3])
+        lum = 0.2126 * rgb_linear[:, 0] + 0.7152 * rgb_linear[:, 1] + 0.0722 * rgb_linear[:, 2]
+        lum_srgb = self._linear_to_srgb(lum)
+        gray_colors = np.column_stack([lum_srgb, lum_srgb, lum_srgb,
+                                       rgba[:, 3]])
+        cmap_name = name or f"{self.name}_grayscale"
+        return ContinuousColormap.from_list(cmap_name, gray_colors.tolist(), N=N)
+
+    def colorblind(self, cvd_type="deuteranopia", N=256, name=None):
+        """
+        Simulate how this colormap appears under color vision deficiency.
+
+        Parameters:
+            cvd_type (str): Type of color vision deficiency. One of
+                            'protanopia', 'deuteranopia', or 'tritanopia'.
+            N (int): Number of quantization levels.
+            name (str): Name for the new colormap.
+
+        Returns:
+            ContinuousColormap: A colormap simulating the specified CVD.
+
+        Example:
+            >>> cmap = Colormap("viridis")
+            >>> deut = cmap.colorblind("deuteranopia")
+        """
+        cvd_type = cvd_type.lower()
+        if cvd_type not in self._CVD_MATRICES:
+            raise ValueError(
+                f"Unknown CVD type '{cvd_type}'. "
+                f"Choose from: {', '.join(self._CVD_MATRICES.keys())}"
+            )
+
+        mat = self._CVD_MATRICES[cvd_type]
+        rgba = self._sample_rgba(N)
+
+        # Convert sRGB → linear → apply CVD matrix → linear → sRGB
+        rgb_linear = self._srgb_to_linear(rgba[:, :3])
+        rgb_cvd = rgb_linear @ mat.T
+        rgb_cvd = np.clip(rgb_cvd, 0, 1)
+        rgb_srgb = self._linear_to_srgb(rgb_cvd)
+        rgb_srgb = np.clip(rgb_srgb, 0, 1)
+
+        cvd_colors = np.column_stack([rgb_srgb, rgba[:, 3]])
+        cmap_name = name or f"{self.name}_{cvd_type}"
+        return ContinuousColormap.from_list(cmap_name, cvd_colors.tolist(), N=N)
+
+    def lightness(self, N=256):
+        """
+        Compute the CIELAB L* lightness profile across the colormap.
+
+        Parameters:
+            N (int): Number of sample points.
+
+        Returns:
+            numpy.ndarray: Array of L* values (0–100) of shape (N,).
+
+        Example:
+            >>> cmap = Colormap("viridis")
+            >>> L = cmap.lightness()
+        """
+        rgba = self._sample_rgba(N)
+        rgb_linear = self._srgb_to_linear(rgba[:, :3])
+
+        # sRGB D65 whitepoint → XYZ conversion (Rec. 709 primaries)
+        M_rgb_to_xyz = np.array([
+            [0.4124564, 0.3575761, 0.1804375],
+            [0.2126729, 0.7151522, 0.0721750],
+            [0.0193339, 0.1191920, 0.9503041],
+        ])
+        xyz = rgb_linear @ M_rgb_to_xyz.T
+
+        # D65 white point
+        Yn = 1.0
+        y_ratio = xyz[:, 1] / Yn
+
+        # CIE L* formula
+        delta = 6.0 / 29.0
+        f_y = np.where(y_ratio > delta ** 3,
+                       np.cbrt(y_ratio),
+                       y_ratio / (3.0 * delta ** 2) + 4.0 / 29.0)
+        L_star = 116.0 * f_y - 16.0
+        return L_star
+
+    def plot_analysis(self, N=256, figsize=None):
+        """
+        Plot a comprehensive colormap analysis panel.
+
+        Shows the original colormap, its grayscale conversion, lightness
+        profile, and three color-vision deficiency simulations (protanopia,
+        deuteranopia, tritanopia).
+
+        Parameters:
+            N (int): Number of sample points.
+            figsize (tuple): Figure size (width, height). Default auto.
+
+        Returns:
+            matplotlib.figure.Figure: The analysis figure.
+
+        Example:
+            >>> cmap = Colormap("viridis")
+            >>> fig = cmap.plot_analysis()
+        """
+        gradient = np.linspace(0, 1, N).reshape(1, -1)
+
+        rows = [
+            ("Original", self),
+            ("Grayscale", self.to_grayscale(N)),
+            ("Protanopia", self.colorblind("protanopia", N)),
+            ("Deuteranopia", self.colorblind("deuteranopia", N)),
+            ("Tritanopia", self.colorblind("tritanopia", N)),
+        ]
+
+        fig_w = figsize[0] if figsize else 10
+        fig_h = figsize[1] if figsize else (len(rows) * 0.6 + 2)
+
+        fig, axes = plt.subplots(len(rows) + 1, 1,
+                                 figsize=(fig_w, fig_h),
+                                 gridspec_kw={"height_ratios":
+                                              [1] * len(rows) + [2]})
+
+        for ax, (label, cm) in zip(axes[:-1], rows):
+            ax.imshow(gradient, aspect="auto", cmap=cm)
+            ax.set_yticks([])
+            ax.set_xticks([])
+            ax.set_ylabel(label, rotation=0, ha="right", va="center",
+                          fontsize=9)
+
+        # Lightness plot
+        ax_l = axes[-1]
+        t = np.linspace(0, 1, N)
+        L = self.lightness(N)
+        L_gray = self.to_grayscale(N).lightness(N)
+
+        # Color the lightness line using the colormap
+        for i in range(N - 1):
+            ax_l.plot(t[i:i + 2], L[i:i + 2], color=self(t[i]), lw=2)
+        ax_l.plot(t, L_gray, color="0.5", lw=1, ls="--", label="grayscale")
+        ax_l.set_ylabel("L*", fontsize=9)
+        ax_l.set_xlabel("Colormap position", fontsize=9)
+        ax_l.set_xlim(0, 1)
+        ax_l.set_ylim(0, 100)
+        ax_l.legend(fontsize=8, loc="best")
+
+        fig.suptitle(f"Colormap analysis: {self.name}", fontsize=11)
+        fig.tight_layout()
+        return fig
+
+
+class ContinuousColormap(_ColormapMixin, mcolors.LinearSegmentedColormap):
+    """
+    Extended LinearSegmentedColormap with additional convenience methods.
+
+    Inherits all functionality from matplotlib's LinearSegmentedColormap
+    and adds methods like sample(), to_palette(), and truncate().
+    """
+
+    @classmethod
+    def from_list(cls, name, colors, N=256, gamma=1.0):
+        """Create a ContinuousColormap from a list of colors."""
+        # Use parent's from_list but ensure we get our subclass back
+        parent_cmap = mcolors.LinearSegmentedColormap.from_list(name, colors, N, gamma)
+        # Create our subclass instance with the same data
+        cmap = cls(name, parent_cmap._segmentdata, N, gamma)
+        return cmap
+
+
+class DiscreteColormap(_ColormapMixin, mcolors.ListedColormap):
+    """
+    Extended ListedColormap with additional convenience methods.
+
+    Inherits all functionality from matplotlib's ListedColormap
+    and adds methods like sample(), to_palette(), and truncate().
+    """
+    pass
+
+
+class Colormap:
+    """
+    Factory for creating extended colormaps with additional methods.
+
+    Creates ContinuousColormap or DiscreteColormap instances that extend
+    matplotlib's colormaps with convenient methods like sample(), to_palette(),
+    and truncate().
+
+    Supports loading from:
+    - Matplotlib colormap names ("viridis", "plasma", etc.)
+    - Scientific colormap names ("batlow", "vik", etc.)
+    - cmap package colormaps ("cmasher:ember", "cmocean:deep", etc.)
+    - Lists of colors (hex strings, RGB tuples, or named colors)
+    - Palette instances
+
+    Usage:
+        cmap = Colormap("viridis")          # Load matplotlib cmap
+        cmap = Colormap("batlow")           # Load scientific cmap
+        cmap = Colormap("cmasher:ember")    # Load from cmap package
+        cmap = Colormap(["#ff0000", "#00ff00", "#0000ff"])  # From colors
+        cmap = Colormap(my_palette)         # From Palette instance
+
+        # Extended methods
+        colors = cmap.sample(5, as_hex=True)
+        palette = cmap.to_palette(n=8)
+        truncated = cmap.truncate(0.2, 0.8)
+    """
+
+    CMAP_BASE_PATH = os.path.join(os.path.dirname(__file__), "scientific_color_maps")
+    CMAP_TYPES = ("sequential", "diverging", "multisequential", "cyclic", "qualitative")
+
+    def __new__(cls, source, name=None, N=256, discrete=False):
+        """
+        Create an extended colormap from various sources.
+
+        Parameters:
+            source: Colormap name (str), list of colors, Palette, or existing colormap.
+            name (str): Optional name override.
+            N (int): Number of RGB quantization levels (for continuous colormaps).
+            discrete (bool): If True, create a DiscreteColormap instead of continuous.
+
+        Returns:
+            ContinuousColormap or DiscreteColormap: An extended matplotlib colormap.
+        """
+        # Already one of our extended colormaps - return as-is
+        if isinstance(source, (ContinuousColormap, DiscreteColormap)):
+            return source
+
+        # Wrap existing matplotlib colormap
+        if isinstance(source, mcolors.Colormap):
+            return cls._wrap_mpl_colormap(source, N)
+
+        # From Palette instance
+        if isinstance(source, Palette):
+            colors = source.get_hex_colors()
+            cmap_name = name or getattr(source, "name", "custom")
+            return cls._from_colors(colors, cmap_name, N, discrete)
+
+        # From list of colors
+        if isinstance(source, (list, tuple)) and not isinstance(source, str):
+            cmap_name = name or "custom"
+            return cls._from_colors(source, cmap_name, N, discrete)
+
+        # From string name - try loading
+        if isinstance(source, str):
+            cmap_name = name or source
+            return cls._load(source, cmap_name, N)
+
+        raise TypeError(f"Cannot create colormap from {type(source)}")
+
+    @classmethod
+    def _wrap_mpl_colormap(cls, cmap, N=256):
+        """Wrap a matplotlib colormap in our extended class."""
+        if isinstance(cmap, mcolors.ListedColormap):
+            new_cmap = DiscreteColormap(cmap.colors, name=cmap.name)
+            return new_cmap
+        else:
+            # Sample and recreate as ContinuousColormap
+            colors = [cmap(i / (N - 1)) for i in range(N)]
+            return ContinuousColormap.from_list(cmap.name, colors, N=N)
+
+    @classmethod
+    def _from_colors(cls, colors, name, N, discrete):
+        """Create colormap from a list of colors."""
+        normalized = [mcolors.to_rgba(c) for c in colors]
+        if discrete:
+            return DiscreteColormap(normalized, name=name)
+        return ContinuousColormap.from_list(name, normalized, N=N)
+
+    @classmethod
+    def _load(cls, name, cmap_name, N):
+        """Load colormap by name (matplotlib, scientific_color_maps, or cmap package)."""
+        # Try matplotlib first
+        try:
+            mpl_cmap = plt.get_cmap(name)
+            return cls._wrap_mpl_colormap(mpl_cmap, N)
+        except ValueError:
+            pass
+
+        # Try scientific colormaps
+        file_path = cls._find_cmap_file(name)
+        if file_path:
+            colors = cls._load_colors_from_file(file_path)
+            return ContinuousColormap.from_list(cmap_name, colors, N=N)
+
+        # Try cmap package
+        if HAS_CMAP:
+            try:
+                cmap_obj = cmap_lib.Colormap(name)
+                mpl_cmap = cmap_obj.to_mpl()
+                return cls._wrap_mpl_colormap(mpl_cmap, N)
+            except Exception:
+                pass
+
+        # Not found
+        available = cls.list_available()
+        all_names = [n for names in available.values() for n in names]
+        hint = ""
+        if ":" in name and not HAS_CMAP:
+            hint = (
+                f" Namespaced colormaps like '{name}' require the 'cmap' "
+                f"package (pip install cmap)."
+            )
+        raise ValueError(
+            f"Colormap '{name}' not found.{hint} "
+            f"Available: {', '.join(all_names[:10])}..."
+        )
+
+    @classmethod
+    def _find_cmap_file(cls, name):
+        """Find the file path for a scientific colormap."""
+        for cmap_type in cls.CMAP_TYPES:
+            file_path = os.path.join(cls.CMAP_BASE_PATH, cmap_type, f"{name}.txt")
+            if os.path.exists(file_path):
+                return file_path
+        return None
+
+    @classmethod
+    def _load_colors_from_file(cls, file_path):
+        """Load RGB colors from a text file (values in 0-1 range)."""
+        colors = []
+        with open(file_path, "r") as f:
+            for line in f:
+                parts = line.strip().split()
+                if len(parts) == 3:
+                    colors.append(tuple(float(v) for v in parts))
+        return colors
+
+    @classmethod
+    def list_available(cls, cmap_type=None, source='all'):
+        """
+        List available colormaps by type and source.
+
+        Parameters:
+            cmap_type (str): 'sequential', 'diverging', 'multisequential', 'cyclic',
+                             'qualitative', or None for all.
+            source (str): 'all' (default), 'Crameri' (scientific folder),
+                          'matplotlib', or 'cmap' (cmap package catalog).
+
+        Returns:
+            dict or list: Dictionary mapping cmap_type to list of colormap names, or list for a single type.
+        """
+        mpl_colormaps = set(plt.colormaps())
+        MPL_DEFAULTS = {
+            'sequential': [
+                'viridis', 'plasma', 'inferno', 'magma', 'cividis', 'Greys', 'Purples', 'Blues', 'Greens', 'Oranges', 'Reds',
+                'YlOrBr', 'YlOrRd', 'OrRd', 'PuRd', 'RdPu', 'BuPu', 'GnBu', 'PuBu', 'YlGnBu', 'PuBuGn', 'BuGn', 'YlGn'
+            ],
+            'diverging': [
+                'PiYG', 'PRGn', 'BrBG', 'PuOr', 'RdGy', 'RdBu', 'RdYlBu', 'RdYlGn', 'Spectral', 'coolwarm', 'bwr', 'seismic'
+            ],
+            'cyclic': [
+                'twilight', 'twilight_shifted', 'hsv'
+            ],
+            'multisequential': [],
+            'qualitative': [],
+        }
+
+        # Mapping from bsplot categories to cmap package categories
+        CMAP_CATEGORY_MAP = {
+            'sequential': 'sequential',
+            'diverging': 'diverging',
+            'cyclic': 'cyclic',
+            'qualitative': 'qualitative',
+            'multisequential': None,  # cmap package has no multisequential category
+        }
+
+        def get_crameri_names(cmaptype):
+            type_path = os.path.join(cls.CMAP_BASE_PATH, cmaptype)
+            if os.path.exists(type_path):
+                names = [
+                    os.path.splitext(f)[0]
+                    for f in os.listdir(type_path)
+                    if f.endswith(".txt") and not re.search(r"(10|25|50|HEX)", f)
+                ]
+                return sorted(names)
+            return []
+
+        def get_mpl_names(cmaptype):
+            return [n for n in MPL_DEFAULTS.get(cmaptype, []) if n in mpl_colormaps]
+
+        def get_cmap_names(cmaptype):
+            """Get colormap names from the cmap package catalog."""
+            if not HAS_CMAP:
+                return []
+            cmap_category = CMAP_CATEGORY_MAP.get(cmaptype)
+            if cmap_category is None:
+                return []
+            try:
+                catalog = cmap_lib.Colormap.catalog()
+                names = sorted(catalog.unique_keys(
+                    prefer_short_names=False,
+                    categories=(cmap_category,),
+                ))
+                return names
+            except Exception:
+                return []
+
+        types_to_check = [cmap_type] if cmap_type else list(cls.CMAP_TYPES)
+
+        if source == 'all':
+            if cmap_type is None:
+                available = {}
+                for cmaptype in types_to_check:
+                    available[cmaptype] = get_mpl_names(cmaptype) + get_crameri_names(cmaptype)
+                return available
+            else:
+                return get_mpl_names(cmap_type) + get_crameri_names(cmap_type)
+        elif source.lower() == 'crameri':
+            if cmap_type is None:
+                available = {}
+                for cmaptype in types_to_check:
+                    available[cmaptype] = get_crameri_names(cmaptype)
+                return available
+            else:
+                return get_crameri_names(cmap_type)
+        elif source.lower() == 'matplotlib':
+            if cmap_type is None:
+                available = {}
+                for cmaptype in types_to_check:
+                    available[cmaptype] = get_mpl_names(cmaptype)
+                return available
+            else:
+                return get_mpl_names(cmap_type)
+        elif source.lower() == 'cmap':
+            if cmap_type is None:
+                available = {}
+                for cmaptype in types_to_check:
+                    available[cmaptype] = get_cmap_names(cmaptype)
+                return available
+            else:
+                return get_cmap_names(cmap_type)
+        else:
+            raise ValueError(f"Unknown source '{source}'. Use 'all', 'Crameri', 'matplotlib', or 'cmap'.")
+
+    @classmethod
+    def load(cls, name, N=256):
+        """
+        Load a colormap by name.
+
+        Parameters:
+            name (str): Colormap name (matplotlib or scientific).
+            N (int): Number of quantization levels.
+
+        Returns:
+            ContinuousColormap or DiscreteColormap
+        """
+        return cls(name, N=N)
+
+    @classmethod
+    def from_colors(cls, colors, name="custom", discrete=False, N=256):
+        """
+        Create a colormap from a list of colors.
+
+        Parameters:
+            colors (list): List of colors (hex strings, RGB tuples, or named colors).
+            name (str): Name for the colormap.
+            discrete (bool): If True, create a DiscreteColormap.
+            N (int): Number of quantization levels (for continuous).
+
+        Returns:
+            ContinuousColormap or DiscreteColormap
+        """
+        return cls(colors, name=name, N=N, discrete=discrete)
+
+    @classmethod
+    def from_palette(cls, palette, discrete=False, N=256):
+        """
+        Create a colormap from a Palette instance.
+
+        Parameters:
+            palette (Palette): A Palette instance.
+            discrete (bool): If True, create a DiscreteColormap.
+            N (int): Number of quantization levels (for continuous).
+
+        Returns:
+            ContinuousColormap or DiscreteColormap
+        """
+        return cls(palette, N=N, discrete=discrete)
+
+    @classmethod
+    def concatenate(cls, cmaps, ratios=None, name="concatenated", N=256):
+        """
+        Concatenate multiple colormaps into a single continuous colormap.
+
+        Parameters:
+            cmaps (list): List of colormaps (names, Colormap instances, or matplotlib colormaps).
+            ratios (list): Relative sizes of each segment. Defaults to equal sizes.
+                           E.g. [1, 2, 1] gives the middle cmap twice the space.
+            name (str): Name for the resulting colormap.
+            N (int): Number of quantization levels.
+
+        Returns:
+            ContinuousColormap: A new colormap combining all inputs.
+
+        Example:
+            >>> purple = Colormap("viridis").truncate(0.0, 0.2)
+            >>> yellow = Colormap("viridis").truncate(0.8, 1.0)
+            >>> combined = Colormap.concatenate([purple, yellow])
+        """
+        if ratios is None:
+            ratios = [1.0] * len(cmaps)
+        ratios = np.array(ratios, dtype=float)
+        ratios /= ratios.sum()
+
+        # Resolve all cmaps
+        resolved = []
+        for c in cmaps:
+            if isinstance(c, str):
+                resolved.append(cls(c))
+            elif isinstance(c, mcolors.Colormap):
+                resolved.append(c)
+            else:
+                raise TypeError(f"Cannot interpret {type(c)} as a colormap.")
+
+        # Sample colors from each cmap proportionally
+        all_colors = []
+        for cmap_obj, ratio in zip(resolved, ratios):
+            n_samples = max(int(round(ratio * N)), 2)
+            t = np.linspace(0, 1, n_samples)
+            all_colors.extend([cmap_obj(v) for v in t])
+
+        return ContinuousColormap.from_list(name, all_colors, N=N)
+
+    @classmethod
+    def make_diverging(cls, low, high, center="white", blend_width=0.3,
+                       low_range=None, high_range=None, name="diverging", N=256):
+        """
+        Create a diverging colormap from two color sources with a blended center.
+
+        Samples colors from the low end and high end, then blends them towards
+        a center color (e.g. white) to create a smooth diverging colormap.
+
+        Parameters:
+            low: Colormap for the low (left) side. Can be a name (str), a Colormap,
+                 or a matplotlib colormap.
+            high: Colormap for the high (right) side.
+            center: Center color to blend towards (default: "white"). Any valid
+                    matplotlib color specification.
+            blend_width (float): Fraction of each half that blends towards the center
+                                 color. 0 = no blending (hard transition), 1 = blend
+                                 across the entire half. Default: 0.3.
+            low_range (tuple): (start, stop) range to sample from the low colormap.
+                               Default: (0, 1).
+            high_range (tuple): (start, stop) range to sample from the high colormap.
+                                Default: (0, 1). Note: this is sampled in reverse
+                                so the high colormap's stop is at the outer edge.
+            name (str): Name for the resulting colormap.
+            N (int): Number of quantization levels.
+
+        Returns:
+            ContinuousColormap: A diverging colormap.
+
+        Example:
+            >>> # Diverging viridis: purple ← white → yellow
+            >>> cmap = Colormap.make_diverging(
+            ...     "viridis", "viridis",
+            ...     low_range=(0, 0.2),
+            ...     high_range=(0.8, 1.0),
+            ...     center="white",
+            ...     blend_width=0.4,
+            ... )
+
+            >>> # Diverging from two different colormaps
+            >>> cmap = Colormap.make_diverging("Blues_r", "Reds")
+
+            >>> # Using existing Colormap objects
+            >>> blue = Colormap("viridis").truncate(0.0, 0.3)
+            >>> red = Colormap("inferno").truncate(0.3, 0.8)
+            >>> cmap = Colormap.make_diverging(blue, red, center="#f0f0f0")
+        """
+        # Resolve colormaps
+        if isinstance(low, str):
+            low = cls(low)
+        if isinstance(high, str):
+            high = cls(high)
+
+        low_start, low_stop = low_range if low_range else (0.0, 1.0)
+        high_start, high_stop = high_range if high_range else (0.0, 1.0)
+
+        half = N // 2
+        center_rgba = np.array(mcolors.to_rgba(center))
+
+        # Sample low side
+        t_low = np.linspace(low_start, low_stop, half)
+        low_colors = np.array([low(v) for v in t_low])
+
+        # Sample high side (reversed so center is at the inner edge)
+        t_high = np.linspace(high_stop, high_start, half)
+        high_colors = np.array([high(v) for v in t_high])
+
+        # Stack: low_colors | high_colors
+        colors = np.vstack([low_colors, high_colors])
+
+        # Blend towards center color
+        if blend_width > 0:
+            n_total = len(colors)
+            mid = n_total // 2
+            for i in range(n_total):
+                dist = abs(i - mid) / mid  # 0 at center, 1 at edges
+                if dist < blend_width:
+                    w = 1.0 - (dist / blend_width)  # 1 at center, 0 at blend edge
+                    colors[i, :] = colors[i, :] * (1.0 - w) + center_rgba * w
+
+        return ContinuousColormap.from_list(name, colors.tolist(), N=N)
+
+
+def get_cmap(name="batlow", N=256):
+    """
+    Get a colormap by name.
+
+    Parameters:
+        name (str): Name of the colormap (matplotlib or scientific).
+        N (int): Number of quantization levels.
+
+    Returns:
+        matplotlib.colors.Colormap: A matplotlib colormap.
+    """
+    return Colormap(name, N=N)
+
+
+def create_cmap_from_lut(lut_file_path, include_zero=False):
+    lut = pd.read_csv(
+        lut_file_path,
+        comment="#",
+        sep=r"\s+",
+        header=None,
+        names=["index", "R", "G", "B", "A"],
+    )
+    lut["A"] = lut.apply(
+        lambda row: 255 if row["index"] not in ["NONE", "Unknown"] else row["A"], axis=1
+    )
+    rgba_colors = lut[["R", "G", "B", "A"]].div(255).to_numpy()
+    if not include_zero:
+        rgba_colors = rgba_colors[1:]
+    cmap = mcolors.ListedColormap(rgba_colors)
+
+    return cmap
+
+
+def cmap_to_colors(
+    cmap="viridis", n=8, start=0.0, stop=1.0, endpoint=True, reverse=False, to_hex=False
+):
+    """
+    Sample a continuous Matplotlib colormap into a list of n colors.
+
+    Parameters:
+        cmap (str or Colormap): Name or instance of a Matplotlib colormap.
+        n (int): Number of samples.
+        start (float): Start of the sampling range in [0, 1].
+        stop (float): End of the sampling range in [0, 1].
+        endpoint (bool): Include the stop value.
+        reverse (bool): Reverse the order of colors.
+        to_hex (bool): Return colors as hex strings instead of RGBA.
+
+    Returns:
+        list: List of colors (RGBA tuples or hex strings).
+    """
+    if isinstance(cmap, str):
+        cmap = Colormap(cmap)
+    t = np.linspace(start, stop, int(n), endpoint=endpoint)
+    if reverse:
+        t = t[::-1]
+    cols = [cmap(v) for v in t]
+    if to_hex:
+        cols = [mcolors.to_hex(c) for c in cols]
+    return cols
+
+
+def make_cycler_from_cmap(
+    cmap="viridis",
+    n=8,
+    start=0.0,
+    stop=1.0,
+    endpoint=True,
+    reverse=False,
+    to_hex=False,
+    return_hex=False,
+):
+    """
+    Build a Matplotlib prop cycler from a continuous colormap.
+
+    Parameters mirror cmap_to_colors. If return_hex=True, return the list of colors
+    (hex if to_hex or return_hex is True) instead of a cycler.
+
+    Returns:
+        cycler | list: cycler('color', colors) by default, or list of colors when return_hex=True.
+    """
+    colors = cmap_to_colors(
+        cmap=cmap,
+        n=n,
+        start=start,
+        stop=stop,
+        endpoint=endpoint,
+        reverse=reverse,
+        to_hex=(to_hex or return_hex),
+    )
+    if return_hex:
+        return colors
+    return cycler("color", colors)
+
+
+def discrete_cmap_from_continuous(
+    cmap="viridis", n=8, start=0.0, stop=1.0, endpoint=True, reverse=False
+):
+    """
+    Create a discrete ListedColormap from a continuous colormap.
+
+    Parameters:
+        cmap (str or Colormap): Name or instance of a Matplotlib colormap.
+        n (int): Number of discrete colors.
+        start (float): Start of the sampling range in [0, 1].
+        stop (float): End of the sampling range in [0, 1].
+        endpoint (bool): Include the stop value.
+        reverse (bool): Reverse the order of colors.
+
+    Returns:
+        ListedColormap: A discrete ListedColormap instance.
+    """
+    colors = cmap_to_colors(
+        cmap=cmap,
+        n=n,
+        start=start,
+        stop=stop,
+        endpoint=endpoint,
+        reverse=reverse,
+    )
+    return mcolors.ListedColormap(colors)
+
+
+# ---------------------------------------------------------------------------
+# Colormap accessibility — computed from actual colormap data
+# ---------------------------------------------------------------------------
+
+def _cmap_has_tag(name, tag):
+    """Check whether a *cmap*-package colormap carries a given catalog tag.
+
+    Uses the live catalog so that newly added colormaps or updated tags
+    are picked up automatically.
+
+    Recognised tags (as of cmap 0.7):
+        'colorblind', 'uniform', 'protanopia', 'deuteranopia', 'tritanopia'
+    """
+    if not HAS_CMAP:
+        return False
+    try:
+        import warnings as _w
+        with _w.catch_warnings():
+            _w.simplefilter("ignore")
+            entry = cmap_lib.Colormap.catalog()[name]
+            return tag in entry.tags
+    except (KeyError, Exception):
+        return False
+
+
+def _luminance_profile(cmap_obj, n_samples=32):
+    """Return the luminance array for a colormap, sampled at *n_samples*
+    evenly-spaced points."""
+    t = np.linspace(0, 1, n_samples)
+    rgba = np.array([cmap_obj(v) for v in t])
+    # Relative luminance (Rec. 709)
+    return 0.2126 * rgba[:, 0] + 0.7152 * rgba[:, 1] + 0.0722 * rgba[:, 2]
+
+
+def _luminance_is_monotonic(cmap_obj, n_samples=32, tolerance=0.04):
+    """Return True if a colormap's perceived luminance is approximately
+    monotonic (either increasing or decreasing).
+
+    This is the *computed* definition of print-friendliness: if the
+    luminance changes monotonically, the colormap reproduces well in
+    greyscale.
+
+    Parameters
+    ----------
+    cmap_obj : matplotlib colormap
+        Any callable that maps [0, 1] → RGBA.
+    n_samples : int
+        Number of points to sample along the colourmap.
+    tolerance : float
+        Fraction of the luminance range by which individual steps may
+        violate strict monotonicity (accounts for small wiggles in
+        otherwise perceptually uniform maps).
+    """
+    lum = _luminance_profile(cmap_obj, n_samples)
+    diffs = np.diff(lum)
+    lum_range = lum.max() - lum.min()
+    if lum_range < 0.05:
+        # Near-constant luminance (e.g. pure-hue cyclic maps) — not useful
+        # in greyscale.
+        return False
+
+    eps = tolerance * lum_range
+    # Check approximately increasing OR approximately decreasing
+    return bool(np.all(diffs > -eps) or np.all(diffs < eps))
+
+
+def _luminance_has_structure(cmap_obj, n_samples=32, tolerance=0.04):
+    """Return True if a colormap encodes information in lightness, making
+    it robust under colour-vision deficiency.
+
+    Accepts:
+    - Monotonic luminance (sequential maps)
+    - V-shaped or Λ-shaped luminance (diverging maps where each half is
+      monotonic in opposite directions)
+    """
+    lum = _luminance_profile(cmap_obj, n_samples)
+    lum_range = lum.max() - lum.min()
+    if lum_range < 0.05:
+        return False
+
+    # 1. Fully monotonic?
+    diffs = np.diff(lum)
+    eps = tolerance * lum_range
+    if np.all(diffs > -eps) or np.all(diffs < eps):
+        return True
+
+    # 2. Diverging structure: split at midpoint — each half monotonic
+    #    in opposite directions (V or Λ shape).
+    mid = n_samples // 2
+    left = lum[:mid + 1]
+    right = lum[mid:]
+    left_diffs = np.diff(left)
+    right_diffs = np.diff(right)
+    left_range = left.max() - left.min()
+    right_range = right.max() - right.min()
+
+    if left_range < 0.03 or right_range < 0.03:
+        return False
+
+    eps_l = tolerance * left_range
+    eps_r = tolerance * right_range
+
+    left_inc = np.all(left_diffs > -eps_l)
+    left_dec = np.all(left_diffs < eps_l)
+    right_inc = np.all(right_diffs > -eps_r)
+    right_dec = np.all(right_diffs < eps_r)
+
+    # V shape: decreasing then increasing, or Λ: increasing then decreasing
+    if (left_dec and right_inc) or (left_inc and right_dec):
+        return True
+
+    return False
+
+
+def _is_colorblind_safe(name, cmap_obj):
+    """Heuristic: a colormap is considered CVD-safe if
+
+    1. the cmap catalog tags it as ``'colorblind'``, **or**
+    2. its luminance has structure (monotonic for sequential, V/Λ-shaped
+       for diverging) — meaning information is encoded in lightness, not
+       just hue, which is inherently robust under CVD.
+    """
+    # Catalog tags (dynamic)
+    if ":" in name and _cmap_has_tag(name, "colorblind"):
+        return True
+    # Compute: structured luminance ≈ CVD-robust
+    return _luminance_has_structure(cmap_obj)
+
+
+def _is_print_friendly(name, cmap_obj):
+    """Heuristic: a colormap is print-friendly if its luminance profile is
+    approximately monotonic, meaning it survives greyscale conversion."""
+    return _luminance_is_monotonic(cmap_obj)
+
+
+# Human-friendly data description → internal cmap type
+_DATA_TYPE_MAP = {
+    "ordered": "sequential", "sequential": "sequential",
+    "centered": "diverging", "diverging": "diverging",
+    "periodic": "cyclic", "cyclic": "cyclic",
+    "categorical": "qualitative", "qualitative": "qualitative",
+    "multirange": "multisequential", "multisequential": "multisequential",
+}
+
+# ---------------------------------------------------------------------------
+# Interactive wizard prompts
+# ---------------------------------------------------------------------------
+def _wizard_prompts():
+    """Run the interactive wizard and return resolved keyword arguments."""
+    print("━" * 50)
+    print("  bsplot Colormap Explorer")
+    print("━" * 50)
+    print()
+
+    # ── Q1  Data character ──────────────────────────────
+    print("What kind of data are you visualising?")
+    print("  1  Ordered / sequential  (intensity, temperature, counts)")
+    print("  2  Centered / diverging  (anomalies, differences, ±values)")
+    print("  3  Periodic / cyclic     (phase, angles, time of day)")
+    print("  4  Categorical           (groups, labels, brain regions)")
+    print("  5  Multi-range           (land / ocean elevation)")
+    c = input("\n▸ Enter number [1-5]: ").strip()
+    data = {
+        "1": "ordered", "2": "centered", "3": "periodic",
+        "4": "categorical", "5": "multirange",
+    }.get(c, "ordered")
+    print()
+
+    # ── Q2  Continuous vs discrete ──────────────────────
+    n_categories = None
+    print("Is your data continuous or discrete?")
+    print("  1  Continuous  (smooth gradient)")
+    print("  2  Discrete    (fixed number of categories)")
+    c = input("\n▸ Enter number [1-2]: ").strip()
+    if c == "2":
+        try:
+            n_categories = int(input("  How many categories? ").strip())
+        except ValueError:
+            n_categories = None
+    print()
+
+    # ── Q3  Colorblind safety ───────────────────────────
+    cb = input("Must be colorblind-safe? [y/N]: ").strip().lower()
+    colorblind_safe = cb in ("y", "yes")
+    print()
+
+    # ── Q4  Print / greyscale ───────────────────────────
+    pf = input("Needs to work in greyscale print? [y/N]: ").strip().lower()
+    print_friendly = pf in ("y", "yes")
+    print()
+
+    # ── Q5  Preview style ──────────────────────────────
+    print("How would you like to preview the colormaps?")
+    print("  1  Gradient bars")
+    print("  2  Heatmap / matrix")
+    print("  3  Brain surface")
+    c = input("\n▸ Enter number [1-3]: ").strip()
+    preview = {"1": "gradient", "2": "matrix", "3": "brain"}.get(c, "gradient")
+    print()
+
+    return data, colorblind_safe, n_categories, print_friendly, preview
+
+
+# ---------------------------------------------------------------------------
+# Preview renderers
+# ---------------------------------------------------------------------------
+def _preview_gradient(names, n_categories, figsize, cmap_type, source):
+    """Gradient-bar gallery."""
+    n = len(names)
+    if figsize is None:
+        figsize = (10, max(2, 0.45 * n))
+
+    fig, axes = plt.subplots(n, 1, figsize=figsize)
+    if n == 1:
+        axes = [axes]
+
+    if n_categories:
+        gradient = np.linspace(0, 1, n_categories).reshape(1, -1)
+        gradient = np.repeat(gradient, 20, axis=0)
+    else:
+        gradient = np.linspace(0, 1, 256).reshape(1, -1)
+
+    for ax, name in zip(axes, names):
+        try:
+            cmap = Colormap(name, N=n_categories) if n_categories else Colormap(name)
+        except Exception:
+            ax.set_visible(False)
+            continue
+        ax.imshow(gradient, aspect="auto", cmap=cmap, interpolation="nearest")
+        ax.set_yticks([])
+        ax.set_xticks([])
+        ax.set_ylabel(name, rotation=0, ha="right", va="center", fontsize=8)
+
+    title = f"Colormaps — {cmap_type}"
+    if source != "all":
+        title += f" ({source})"
+    fig.suptitle(title, fontsize=12, fontweight="bold")
+    plt.tight_layout()
+    plt.show()
+
+
+def _preview_matrix(names, n_categories, figsize):
+    """Heatmap gallery on synthetic 2-D data."""
+    ncols = min(4, len(names))
+    nrows = (len(names) + ncols - 1) // ncols
+    if figsize is None:
+        figsize = (3.5 * ncols, 3 * nrows)
+
+    x = np.linspace(-3, 3, 120)
+    X, Y = np.meshgrid(x, x)
+    Z = np.sin(X) * np.cos(Y)
+
+    fig, axs = plt.subplots(nrows, ncols, figsize=figsize, constrained_layout=True)
+    axs = np.atleast_1d(axs).ravel()
+    for ax in axs:
+        ax.axis("off")
+
+    for ax, name in zip(axs, names):
+        try:
+            cmap = Colormap(name, N=n_categories) if n_categories else Colormap(name)
+        except Exception:
+            continue
+        im = ax.imshow(Z, cmap=cmap, origin="lower")
+        ax.set_title(name, fontsize=8)
+        fig.colorbar(im, ax=ax, shrink=0.7)
+
+    fig.suptitle("Colormap preview — heatmap", fontsize=12, fontweight="bold")
+    plt.show()
+
+
+def _preview_brain(names, n_categories, figsize):
+    """Brain-surface gallery."""
+    try:
+        import random as _random
+        import templateflow
+        import nibabel as nib
+        from bsplot import surface as bssurface, style as _style
+    except ImportError:
+        print(
+            "Brain preview requires 'nibabel' and 'templateflow'. "
+            "Falling back to gradient bars."
+        )
+        _preview_gradient(names, n_categories, figsize, "—", "all")
+        return
+
+    fsLR_lh = templateflow.api.get(
+        template="fsLR", density="32k", suffix="inflated", hemi="L",
+    )
+    lh = nib.load(fsLR_lh)
+    vertices, _ = lh.agg_data()
+    centre = _random.choice(range(len(vertices)))
+    distances = np.linalg.norm(vertices - vertices[centre], axis=1)
+    overlay = np.exp(-0.5 * (distances / 100.0) ** 2)
+
+    ncols = min(4, len(names))
+    nrows = (len(names) + ncols - 1) // ncols
+    if figsize is None:
+        figsize = (3.5 * ncols, 2.5 * nrows)
+
+    fig, axs = plt.subplots(nrows, ncols, figsize=figsize, constrained_layout=True)
+    axs = np.atleast_1d(axs).ravel()
+    for ax in axs:
+        ax.axis("off")
+
+    for ax, name in zip(axs, names):
+        try:
+            cmap = Colormap(name, N=n_categories) if n_categories else Colormap(name)
+        except Exception:
+            continue
+        mappable = bssurface.plot_surf(
+            surface="fsLR", overlay=overlay,
+            ax=ax, view="lateral", hemi="lh", cmap=cmap,
+        )
+        fig.colorbar(mappable, ax=ax, shrink=0.6)
+        ax.set_title(name, fontsize=8)
+
+    _style.format_fig(fig)
+    plt.show()
+
+
+# ---------------------------------------------------------------------------
+# Main explorer
+# ---------------------------------------------------------------------------
+def explore_colormaps(
+    data=None,
+    colorblind_safe=None,
+    n_categories=None,
+    print_friendly=None,
+    preview=None,
+    source="all",
+    search=None,
+    max_display=24,
+    figsize=None,
+):
+    """Guided colormap explorer — find the best colormap for your plotting
+    problem.
+
+    Call with **no arguments** for an interactive wizard that walks you through
+    your requirements step by step, or pass keyword arguments directly for
+    scripted use.
+
+    Parameters
+    ----------
+    data : str, optional
+        Describes what you are plotting.  Human-friendly aliases are supported:
+
+        ==============  ================  ===================================
+        Alias           Internal type     When to use
+        ==============  ================  ===================================
+        ``'ordered'``   sequential        intensity, temperature, counts
+        ``'centered'``  diverging         anomalies, correlation, differences
+        ``'periodic'``  cyclic            phase, angles, time of day
+        ``'categorical'`` qualitative     groups, labels, brain regions
+        ``'multirange'`` multisequential  land / ocean elevation
+        ==============  ================  ===================================
+
+        If *None* (the default), the interactive wizard is launched.
+    colorblind_safe : bool, optional
+        Keep only colormaps that are designed for colour-vision deficiency.
+        All Crameri colormaps, the *viridis* family, and most cmasher / cmocean
+        maps pass this filter.  Default *False* (or asked in wizard mode).
+    n_categories : int, optional
+        If set, show discrete colour swatches (``Colormap(name, N=n)``)
+        instead of a smooth gradient.  Useful for categorical data.
+    print_friendly : bool, optional
+        Keep only colormaps whose monotonically increasing luminance
+        reproduces well in greyscale print.
+    preview : str, optional
+        How to preview the candidates:
+
+        * ``'gradient'`` — colour gradient bars (default)
+        * ``'matrix'``   — 2-D heatmap on sample data
+        * ``'brain'``    — lateral brain-surface view (requires *nibabel* &
+          *templateflow*)
+    source : str
+        ``'all'``, ``'matplotlib'``, ``'Crameri'``, or ``'cmap'``.
+    search : str, optional
+        Case-insensitive substring filter on colormap names.
+    max_display : int
+        Maximum number of colormaps to show (default 24).
+    figsize : tuple, optional
+        Matplotlib figure size override.
+
+    Returns
+    -------
+    list of str
+        Names of the colormaps that were displayed.
+
+    Examples
+    --------
+    >>> explore_colormaps()                                  # launch wizard
+    >>> explore_colormaps("ordered", colorblind_safe=True)
+    >>> explore_colormaps("centered", preview="brain", max_display=12)
+    >>> explore_colormaps("periodic", source="cmap")
+    """
+    # ── wizard mode when called bare ───────────────────────
+    interactive = data is None
+    if interactive:
+        data, colorblind_safe, n_categories, print_friendly, preview = (
+            _wizard_prompts()
+        )
+
+    # ── defaults for scripted calls ────────────────────────
+    if colorblind_safe is None:
+        colorblind_safe = False
+    if print_friendly is None:
+        print_friendly = False
+    if preview is None:
+        preview = "gradient"
+
+    # ── resolve cmap type ──────────────────────────────────
+    cmap_type = _DATA_TYPE_MAP.get(data, "sequential")
+
+    # ── collect candidates ─────────────────────────────────
+    available = Colormap.list_available(cmap_type=cmap_type, source=source)
+    if isinstance(available, dict):
+        names = [n for v in available.values() for n in v]
+    else:
+        names = list(available)
+
+    # ── filter: colorblind safety (computed) ─────────────────
+    if colorblind_safe:
+        def _cb(n):
+            try:
+                cmap_obj = Colormap(n)
+                return _is_colorblind_safe(n, cmap_obj)
+            except Exception:
+                return False
+        names = [n for n in names if _cb(n)]
+
+    # ── filter: print-friendly (computed) ──────────────────
+    if print_friendly:
+        def _pf(n):
+            try:
+                cmap_obj = Colormap(n)
+                return _is_print_friendly(n, cmap_obj)
+            except Exception:
+                return False
+        names = [n for n in names if _pf(n)]
+
+    # ── filter: keyword search ─────────────────────────────
+    if search:
+        sl = search.lower()
+        names = [n for n in names if sl in n.lower()]
+
+    names = names[:max_display]
+
+    if not names:
+        print("No colormaps match your criteria. Try relaxing some filters.")
+        return []
+
+    # ── render ─────────────────────────────────────────────
+    if preview == "matrix":
+        _preview_matrix(names, n_categories, figsize)
+    elif preview == "brain":
+        _preview_brain(names, n_categories, figsize)
+    else:
+        _preview_gradient(names, n_categories, figsize, cmap_type, source)
+
+    # ── summary ────────────────────────────────────────────
+    print(f"\n{len(names)} colormaps shown.  Load with:  Colormap('name')")
+    if n_categories:
+        print(f"  Discrete version:  Colormap('name', N={n_categories})")
+
+    return names