"""Plot a log-scale 2D histogram heatmap on a matplotlib Axes."""

from __future__ import annotations


def plot_heatmap_log(
    ax: "Axes",
    xs: "list[float] | np.ndarray",
    ys: "list[float] | np.ndarray",
    extent: "tuple[float, float, float, float]",
    bins: int = 200,
    cmap: str = "hot",
    alpha: float = 0.6,
) -> None:
    """Plot a log-scale 2D density heatmap using histogram binning.

    Computes a 2D histogram over the given points within ``extent``, applies
    log1p to compress the dynamic range, and renders the result as an image
    overlay on the Axes.

    Args:
        ax: matplotlib Axes to draw on.
        xs: X coordinates (longitude or projected x).
        ys: Y coordinates (latitude or projected y).
        extent: Bounding box as (minx, maxx, miny, maxy).
        bins: Number of histogram bins along each axis. Default 200.
        cmap: Matplotlib colormap name. Default "hot".
        alpha: Opacity of the heatmap overlay (0–1). Default 0.6.
    """
    import numpy as np  # type: ignore

    xs_arr = np.asarray(xs, dtype=float)
    ys_arr = np.asarray(ys, dtype=float)

    minx, maxx, miny, maxy = extent

    counts, _xedges, _yedges = np.histogram2d(
        xs_arr,
        ys_arr,
        bins=bins,
        range=[[minx, maxx], [miny, maxy]],
    )

    log_counts = np.log1p(counts.T)

    ax.imshow(
        log_counts,
        extent=[minx, maxx, miny, maxy],
        origin="lower",
        cmap=cmap,
        alpha=alpha,
        aspect="auto",
    )