gsplot.cmap_legend#

cmap_legend(ax, *, cmap='viridis', label=None, stripes=8, norm=None, reverse=False, replace=False, props=None, **kwargs)#

Create one native Legend entry containing a horizontal color gradient.

Parameters:

  • ax (Axes) – Explicit target Axes.

  • cmap (str | Colormap) – Colormap name or native Colormap object.

  • label (str | None) – Optional label for the gradient entry. None creates an empty native Legend and does not render a gradient.

  • stripes (int) – Positive requested stripe count. Counts above 256 are clamped to 256 before sampling and rendering.

  • norm (tuple[float, float] | _NormalizeProtocol | None) – Optional normalizer applied to linspace(0, 1, N_effective) with clip=True. A pair is interpreted as (vmin, vmax) for a read-only Normalize operation; it is not a legacy raw-value alias.

  • reverse (bool) – Reverse the final sampled RGBA sequence from left to right.

  • replace (bool) – Remove an existing legend only when explicitly set to True.

  • props (Mapping[str, Any] | None) – Optional finite Matplotlib Legend constructor properties.

  • **kwargs (Any) – Optional direct Matplotlib Legend constructor properties. Direct keyword arguments are merged with and take precedence over props.

Returns:

The native local Legend.

Return type:

matplotlib.legend.Legend

Raises:

PlotError – If colormap, normalization, stripe count, target, replacement, or properties are invalid.

Notes

The gradient is rendered by one module-level local handler and one proxy handle. It does not modify Matplotlib’s default handler map or add a colormap proxy to the Axes. When replace is false, an existing Legend raises LayoutError; when it is true, the existing Legend is replaced transactionally.

Examples

>>> import gsplot as gs
>>> figure, ax = gs.subplots()
>>> item = gs.cmap_legend(ax, label="intensity")
>>> item.axes is ax
True
>>> figure.clear()