feat: add top level to_mpl convenience (#91)

* feat: add top level to_mpl convenience

* add test

* move test

Author: tlambert03

src/cmap/__init__.py

@@ -11,6 +11,7 @@
 
 from ._color import HSLA, HSVA, RGBA, RGBA8, Color, ColorLike
 from ._colormap import Colormap, ColormapLike, ColorStop, ColorStops
+from ._util import to_mpl
 
 if TYPE_CHECKING:
     from ._catalog import CatalogItem
@@ -74,4 +75,5 @@ def resolve(self, name: str) -> str:
     "ColorStops",
     "Colormap",
     "ColormapLike",
+    "to_mpl",
 ]

src/cmap/_util.py

@@ -9,11 +9,15 @@
 gradient = np.vstack((gradient, gradient))
 
 if TYPE_CHECKING:
+    import matplotlib.colors
     from matplotlib.figure import Figure as MplFigure
     from numpy.typing import ArrayLike, NDArray
 
     from cmap import Colormap
 
+    from ._color import ColorLike
+    from ._colormap import ColorStopsLike, Interpolation
+
 
 def _ensure_cmap(cmap: Colormap | str) -> Colormap:
     from cmap import Colormap
@@ -498,6 +502,40 @@ def report(cm: Colormap, n: int = 256, uniform_space: str = "CAM02-UCS") -> Repo
     # H -> hue composition
 
 
+def to_mpl(
+    value: ColorStopsLike,
+    /,
+    *,
+    name: str | None = None,
+    identifier: str | None = None,
+    category: str | None = None,
+    interpolation: Interpolation | bool | None = None,
+    under: ColorLike | None = None,
+    over: ColorLike | None = None,
+    bad: ColorLike | None = None,
+    N: int = 256,
+    gamma: float = 1.0,
+) -> matplotlib.colors.Colormap:
+    """Convienence function to create a matplotlib colormap.
+
+    Arguments are the same as for [cmap.Colormap][]. This simply creates the
+    colormap instance and returns the value of `to_matplotlib()`.
+    """
+    from cmap import Colormap
+
+    cm = Colormap(
+        value,
+        name=name,
+        identifier=identifier,
+        category=category,
+        interpolation=interpolation,
+        under=under,
+        over=over,
+        bad=bad,
+    )
+    return cm.to_matplotlib(N=N, gamma=gamma)
+
+
 if __name__ == "__main__":  # pragma: no cover
     import matplotlib.pyplot as plt
 

tests/test_third_party.py

@@ -7,6 +7,7 @@
 import numpy as np
 import pytest
 
+import cmap
 from cmap import Color, Colormap
 
 try:
@@ -184,8 +185,7 @@ def test_pyqtgraph() -> None:
     cm.reverse()
 
 
-# def microvis_imshow(img_data: np.ndarray, cmap: cmap.Colormap) -> None:
-#     from microvis import _util, imshow
+def test_to_mpl() -> None:
+    colors = pytest.importorskip("matplotlib.colors")
 
-#     with _util.exec_if_new_qt_app():
-#         imshow(img_data, cmap=cmap)
+    assert isinstance(cmap.to_mpl("viridis"), colors.Colormap)