cmap: Scientific Colormaps for Python

Common errors

• AttributeError: module 'cmap' has no attribute 'my_colormap_name'

  cause Trying to access a colormap directly as an attribute of the top-level `cmap` module or `Colormap` class without using `get_cmap` or the correct namespace.
  fix Use `from cmap import get_cmap; my_cmap = get_cmap('my_colormap_name')` or access through its specific namespace, e.g., `from cmap import Colormap; my_cmap = Colormap.scientific.my_colormap_name`.

• ModuleNotFoundError: No module named 'matplotlib'

  cause Although `matplotlib` is a direct dependency, this error can occur if `cmap` was installed with `--no-deps`, if your Python environment is corrupted, or if `matplotlib` failed to install properly.
  fix Ensure `matplotlib` is correctly installed in your environment: `pip install matplotlib` or `pip install cmap` without `--no-deps`.

• TypeError: Colormap 'my_parametrized_colormap' expects keyword arguments: ['segment_colors']

  cause Attempting to create or retrieve a parametrized colormap without providing its required keyword arguments.
  fix Check the colormap's documentation or source for expected parameters. Pass the required keyword arguments, e.g., `get_cmap('my_parametrized_colormap', segment_colors=['red', 'green', 'blue'])`.

Warnings

• breaking Python 3.8 support was dropped in `cmap` version 0.6.0. Users on Python 3.8 or older will encounter errors or be unable to install recent versions.
  Fix: Upgrade to Python 3.9 or newer (e.g., `python -m pip install --upgrade python` or update your environment).
• breaking The `crameri` colormaps were updated to version 8 in `cmap` v0.5.0. If you relied on pixel-perfect color values for `crameri` colormaps from older versions, these may have changed slightly.
  Fix: Review any code that depends on exact `crameri` color values when upgrading from versions prior to 0.5.0. Consider pinning `cmap<0.5.0` if strict adherence to old `crameri` maps is required.
• gotcha While many colormaps can be accessed via `cmap.get_cmap("name")`, some are organized into namespaces (e.g., `cmap.scientific.viridis`, `cmap.QUALITATIVE.tol.bright`). Attempting to access `cmap.name` directly for a namespaced colormap will result in an `AttributeError`.
  Fix: Always use `get_cmap("name")` for general access, or explicitly specify the namespace like `Colormap.scientific.viridis` when you know the colormap's location.
• gotcha Some colormaps in `cmap` are 'parametrized' and require keyword arguments during instantiation (e.g., `Colormap.linear_segmented(...)`). If you try to instantiate these without the required arguments, a `TypeError` will be raised.
  Fix: Consult the documentation for the specific colormap to understand its required parameters. For example, `my_parametrized_cmap = Colormap.get_cmap('my_param_map', arg1=value1, arg2=value2)` or `Colormap.linear_segmented(colors=['red', 'blue'])`.

Install

• pip install cmap Install stable version

Imports

• Colormap

  from cmap import Colormap

• get_cmap

  from cmap import get_cmap

Quickstart

This quickstart demonstrates how to fetch a colormap using `get_cmap`, convert data to RGBA colors, and integrate the `cmap` colormap with Matplotlib for visualization via the `to_mpl()` method.

import numpy as np
import matplotlib.pyplot as plt
from cmap import get_cmap, Colormap

# Get a colormap by name using the utility function
my_cmap = get_cmap("viridis")

# Or, access namespaced colormaps directly
# my_cmap = Colormap.scientific.viridis

# Colormap objects are callable with normalized data [0, 1] or raw data
data = np.linspace(0, 1, 256) # Example data
colors_rgba = my_cmap(data) # Returns (N, 4) array of RGBA floats

# Convert to a Matplotlib colormap for seamless integration with plotting
mpl_cmap = my_cmap.to_mpl()

# Example usage with Matplotlib
fig, ax = plt.subplots(figsize=(6, 1))
plt.imshow([np.arange(256)], cmap=mpl_cmap, aspect='auto')
plt.colorbar(ax.images[0], orientation='horizontal')
plt.title(f"Example Colormap: {my_cmap.name}")
plt.axis('off')
plt.show()