gsplot.cmap_legend#
- cmap_legend(ax: Axes, *, cmap: str | Colormap = 'viridis', label: str | None = None, stripes: int = 8, norm: tuple[float, float] | _NormalizeProtocol | None = None, reverse: bool = False, replace: bool = False, props: Mapping[str, Any] | None = None, **kwargs: Any) Legend#
- cmap_legend(ax: Axes, *, cmap: str | Colormap | Sequence[str | Colormap] = 'viridis', label: str | Sequence[str] | None = None, stripes: int | Sequence[int] = 8, norm: tuple[float, float] | _NormalizeProtocol | None = None, reverse: bool | Sequence[bool] = False, replace: bool = False, props: Mapping[str, Any] | None = None, **kwargs: Any) Legend
Create native Legend entries containing horizontal color gradients.
- Parameters:
ax (Axes) β Explicit target Axes.
cmap (str | Colormap | Sequence[str | Colormap]) β Colormap name or native Colormap object, shared by every row or supplied once per row.
label (str | Sequence[str] | None) β Label for one gradient entry, or one label per row.
Nonecreates an empty native Legend and does not render a gradient.stripes (int | Sequence[int]) β Positive requested stripe count, shared by every row or supplied once per row. Counts above 256 are clamped to 256 before sampling and rendering.
norm (tuple[float, float] | _NormalizeProtocol | None) β Optional normalizer shared by every row. It is applied to
linspace(0, 1, N_effective)withclip=True. A pair is interpreted as(vmin, vmax)for a read-onlyNormalizeoperation; it is not a legacy raw-value alias.reverse (bool | Sequence[bool]) β Reverse the final sampled RGBA sequence from left to right, shared by every row or supplied once per row.
replace (bool) β Reset to the requested entries only when explicitly set to
True. Without it, a repeated labeled call appends its rows to the existing canonical colormap Legend in call order. Appended calls accept no legend properties.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. Row sequences with different lengths, an empty row sequence, or row sequences combined with
label=NoneraiseLayoutError.
Notes
Each row adds one gradient entry with its own module-level local handler and proxy handle. It does not modify Matplotlibβs default handler map or add a colormap proxy to the Axes. Without
replace, a repeated labeled call appends to the existing canonical colormap Legend: recorded entries keep their colors and order, recorded properties are preserved, and the combined Legend replaces the previous one transactionally. Presentation properties belong to the first call: passingpropsor keyword arguments on an appended call raisesLayoutError. An existing foreign Legend, multiple existing Legends, an ordinary Legend created bylegend, orlabel=Nonestill raiseLayoutError; writecmap_legendcalls beforelegend, or usereplace=True. Withreplace=True, any existing Legend is replaced transactionally. A repeated or merged Legend replaces the previous one, so previously returned Legend objects on that Axes are detached; measure and move only the newly returned object.Examples
>>> import gsplot as gs >>> figure, ax = gs.subplots() >>> item = gs.cmap_legend(ax, label="intensity") >>> item.axes is ax True >>> multi = gs.cmap_legend( ... ax, ... label=["4.7 K", "4.8 K"], ... cmap=["viridis", "plasma"], ... replace=True, ... ) >>> [text.get_text() for text in multi.get_texts()] ['4.7 K', '4.8 K'] >>> figure.clear()