HeatmapSelect API#

def __init__(
    self,
    image: Any,
    *,
    x_range: Tuple[float, float] = (0.0, 1.0),
    y_range: Tuple[float, float] = (0.0, 1.0),
    x_label: str = "",
    y_label: str = "",
    x_suffix: str = "",
    y_suffix: str = "",
    origin: str = "lower",
    cell_width: int = 4,
    cell_height: int = 4,
    row_color: str = "",
    col_color: str = "",
    cmap: Any = "gray",
    norm: Any = None,
    vmin: Optional[float] = None,
    vmax: Optional[float] = None,
    throttle: Union[int, str] = 50,
    **kwargs: Any,
):
    """Create a HeatmapSelect widget.

    Args:
        image: The grid bitmap — one pixel per cell. Accepts a base64/data-URI
            PNG string, a path, a PIL ``Image``, an ``(rows, cols, 3|4)`` uint8
            array, or a ``(rows, cols)`` numeric array colormapped via
            ``cmap``/``norm``/``vmin``/``vmax``.
        x_range: Data coordinates of the first and last *column* centers.
        y_range: Data coordinates of the first and last *row* centers.
        x_label: Label drawn under the bottom gutter.
        y_label: Label drawn beside the left gutter.
        x_suffix: Suffix appended to x tick labels, e.g. ``"°"``.
        y_suffix: Suffix appended to y tick labels.
        origin: ``"lower"`` puts image row 0 at ``y_range[0]`` (bottom),
            ``"upper"`` puts it at the top, matching matplotlib's ``imshow``.
        cell_width: Screen pixels per cell horizontally.
        cell_height: Screen pixels per cell vertically.
        row_color: Tint for the row band grabbed from the left (y) axis, e.g.
            ``"#1f4fd8"``. Empty uses the ``--hs-row-color`` CSS variable.
        col_color: Tint for the column band grabbed from the bottom (x) axis.
            Empty uses the ``--hs-col-color`` CSS variable.
        cmap: Colormap name or ``matplotlib.colors.Colormap``, for 2D numeric
            arrays. Grayscale by default. Mask cells (or make them NaN) and
            use ``cmap.with_extremes(bad="red")`` to color a crash region.
        norm: Optional ``matplotlib.colors.Normalize`` instance, e.g.
            ``LogNorm()``. Mutually exclusive with ``vmin``/``vmax``.
        vmin: Optional lower end of the color scale.
        vmax: Optional upper end of the color scale.
        throttle: How often hover updates reach Python — ``0`` for every
            mouse move, an int for milliseconds, or ``"dragend"`` to send
            hover only on release. Pin changes always sync immediately,
            whatever this is set to.
        **kwargs: Forwarded to ``anywidget.AnyWidget``.
    """
    if origin not in ("lower", "upper"):
        raise ValueError(f"origin must be 'lower' or 'upper', got {origin!r}")
    if cell_width < 1 or cell_height < 1:
        raise ValueError("cell_width and cell_height must be at least 1")
    for name, value in (("x_range", x_range), ("y_range", y_range)):
        if len(tuple(value)) != 2:
            raise ValueError(f"{name} must be a (min, max) pair, got {value!r}")

    # Remembered so set_image() recolors the same way without repeating them.
    self._color_kwargs = {"cmap": cmap, "norm": norm, "vmin": vmin, "vmax": vmax}
    image_base64, n_rows, n_cols = _image_to_png_base64(
        image, **self._color_kwargs
    )

    super().__init__(
        image_base64=image_base64,
        n_rows=n_rows,
        n_cols=n_cols,
        x_range=tuple(float(v) for v in x_range),
        y_range=tuple(float(v) for v in y_range),
        x_label=x_label,
        y_label=y_label,
        x_suffix=x_suffix,
        y_suffix=y_suffix,
        origin=origin,
        cell_width=cell_width,
        cell_height=cell_height,
        row_color=row_color,
        col_color=col_color,
        throttle=throttle,
        **kwargs,
    )