From 089179130a3e7b2576240342d48981a0997696ca Mon Sep 17 00:00:00 2001 From: koaning Date: Tue, 24 Mar 2026 15:24:43 +0100 Subject: [PATCH 1/2] Add HoverZoom widget for image magnification on hover Co-Authored-By: Claude Opus 4.6 --- CHANGELOG.md | 3 + README.md | 3 + agents.md | 1 + demos/hoverzoom.py | 86 ++++++++++++++++++ mkdocs/index.md | 5 ++ mkdocs/llms.txt | 1 + wigglystuff/__init__.py | 2 + wigglystuff/hover_zoom.py | 80 +++++++++++++++++ wigglystuff/static/hover-zoom.css | 55 ++++++++++++ wigglystuff/static/hover-zoom.js | 142 ++++++++++++++++++++++++++++++ 10 files changed, 378 insertions(+) create mode 100644 demos/hoverzoom.py create mode 100644 wigglystuff/hover_zoom.py create mode 100644 wigglystuff/static/hover-zoom.css create mode 100644 wigglystuff/static/hover-zoom.js diff --git a/CHANGELOG.md b/CHANGELOG.md index 18f48dd9..a9c9cb64 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,9 @@ All notable changes to this project will be documented in this file. ## [Unreleased] +### Added +- New `HoverZoom` widget — hover over an image to see a magnified side panel, like product zoom on e-commerce sites. + ## [0.2.40] - 2026-03-24 ### Added diff --git a/README.md b/README.md index fe8c939e..3475c7d8 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,9 @@ uv pip install wigglystuff ColorPicker

molab · API · MD +HoverZoom

molab · API · MD + + GamepadWidget

molab · API · MD KeystrokeWidget

molab · API · MD SpeechToText

molab · API · MD diff --git a/agents.md b/agents.md index 99d65e5c..f7ea9d46 100644 --- a/agents.md +++ b/agents.md @@ -35,6 +35,7 @@ syncs back to Python. | ThreeWidget | `wigglystuff.three_widget.ThreeWidget` | `data`, `width`, `height`, `show_grid`, `show_axes`, `dark_mode`, `axis_labels`, `animate_updates`, `animation_duration_ms` | 3D scatter plot for point clouds | | WebcamCapture | `wigglystuff.webcam_capture.WebcamCapture` | `image_base64`, `capturing`, `interval_ms`, `facing_mode` | Webcam preview with snapshot capture | | GamepadWidget | `wigglystuff.gamepad.GamepadWidget` | `axes`, `current_button_press`, `dpad_*`, `current_timestamp` | Streams browser Gamepad API events | +| HoverZoom | `wigglystuff.hover_zoom.HoverZoom` | `image`, `zoom_factor`, `width`, `height` | Image hover zoom with magnified side panel | | KeystrokeWidget | `wigglystuff.keystroke.KeystrokeWidget` | `last_key` | Captures the latest keypress w/ modifiers | | WebkitSpeechToTextWidget | `wigglystuff.talk.WebkitSpeechToTextWidget` | `transcript`, `listening`, `trigger_listen` | WebKit speech recognition bridge | | DriverTour | `wigglystuff.driver_tour.DriverTour` | `steps`, `auto_start`, `show_progress`, `active`, `current_step` | Guided product tours via Driver.js | diff --git a/demos/hoverzoom.py b/demos/hoverzoom.py new file mode 100644 index 00000000..e297708f --- /dev/null +++ b/demos/hoverzoom.py @@ -0,0 +1,86 @@ +# /// script +# requires-python = ">=3.14" +# dependencies = [ +# "marimo>=0.19.7", +# "wigglystuff==0.2.37", +# "Pillow", +# "matplotlib", +# "numpy", +# ] +# /// + +import marimo + +__generated_with = "0.21.1" +app = marimo.App(width="medium") + + +@app.cell +def _(): + import marimo as mo + from wigglystuff import HoverZoom + + return HoverZoom, mo + + +@app.cell +def _(): + from PIL import Image, ImageDraw + + img = Image.new("RGB", (800, 600), (30, 80, 120)) + draw = ImageDraw.Draw(img) + for i in range(0, 800, 40): + for j in range(0, 600, 40): + color = ((i * 3) % 256, (j * 4) % 256, ((i + j) * 2) % 256) + draw.ellipse([i, j, i + 30, j + 30], fill=color) + return (img,) + + +@app.cell +def _(HoverZoom, img, mo): + widget = mo.ui.anywidget(HoverZoom(img, zoom_factor=3.0, width=450)) + return (widget,) + + +@app.cell +def _(widget): + widget + return + + +@app.cell +def _(): + import numpy as np + import matplotlib + matplotlib.use("Agg") + import matplotlib.pyplot as plt + + rng = np.random.default_rng(42) + n = 200 + x = rng.normal(0, 1, n) + y = rng.normal(0, 1, n) + labels = [f"p{i}" for i in range(n)] + + fig, ax = plt.subplots(figsize=(8, 6), dpi=200) + ax.scatter(x, y, s=12, alpha=0.6) + for xi, yi, label in zip(x, y, labels): + ax.annotate(label, (xi, yi), fontsize=4, alpha=0.7, ha="center", va="bottom") + ax.set_title("200 labeled points — hover to read the labels") + fig.tight_layout() + return (fig,) + + +@app.cell +def _(HoverZoom, fig, mo): + chart_widget = mo.ui.anywidget(HoverZoom(fig, zoom_factor=4.0, width=500)) + return (chart_widget,) + + +@app.cell +def _(chart_widget): + chart_widget + return + + +if __name__ == "__main__": + app.run() diff --git a/mkdocs/index.md b/mkdocs/index.md index 0b00f1c8..64511078 100644 --- a/mkdocs/index.md +++ b/mkdocs/index.md @@ -66,6 +66,11 @@ The documentation for wigglystuff is designed for humans (via hosted marimo note
molabAPIMD
+
HoverZoom
+HoverZoom widget +
molabAPIMD
+
+
GamepadWidget
GamepadWidget
molabAPIMD
diff --git a/mkdocs/llms.txt b/mkdocs/llms.txt index 22865c27..e872b940 100644 --- a/mkdocs/llms.txt +++ b/mkdocs/llms.txt @@ -22,6 +22,7 @@ Install via `pip install wigglystuff` or `uv pip install wigglystuff`. - [ColorPicker](https://koaning.github.io/wigglystuff/reference/color-picker.md): Color selection widget - [CopyToClipboard](https://koaning.github.io/wigglystuff/reference/copy-to-clipboard.md): Copy text to clipboard - [Tangle Widgets](https://koaning.github.io/wigglystuff/reference/tangle.md): Bret Victor-style tangle controls +- [HoverZoom](https://koaning.github.io/wigglystuff/reference/hover-zoom.md): Image hover zoom with magnified side panel - [GamepadWidget](https://koaning.github.io/wigglystuff/reference/gamepad.md): Gamepad controller input - [WebcamCapture](https://koaning.github.io/wigglystuff/reference/webcam-capture.md): Webcam image capture - [CellTour](https://koaning.github.io/wigglystuff/reference/cell-tour.md): Guided notebook tours diff --git a/wigglystuff/__init__.py b/wigglystuff/__init__.py index 73c1eec7..f4cce88a 100644 --- a/wigglystuff/__init__.py +++ b/wigglystuff/__init__.py @@ -16,6 +16,7 @@ from .edge_draw import EdgeDraw from .env_config import EnvConfig from .gamepad import GamepadWidget +from .hover_zoom import HoverZoom from .html import HTMLRefreshWidget, ImageRefreshWidget, ProgressBar from .keystroke import KeystrokeWidget from .matrix import Matrix @@ -74,6 +75,7 @@ "ThreeWidget", "WandbChart", "WebcamCapture", + "HoverZoom", "HTMLRefreshWidget", "ImageRefreshWidget", "ProgressBar", diff --git a/wigglystuff/hover_zoom.py b/wigglystuff/hover_zoom.py new file mode 100644 index 00000000..ea93c5e8 --- /dev/null +++ b/wigglystuff/hover_zoom.py @@ -0,0 +1,80 @@ +"""HoverZoom widget — magnified side panel on image hover.""" + +from __future__ import annotations + +from pathlib import Path +from typing import Any, Optional, Union + +import anywidget +import traitlets + +from .chart_puck import fig_to_base64 +from .paint import base64_to_pil, input_to_pil, pil_to_base64 + + +class HoverZoom(anywidget.AnyWidget): + """Image widget with a magnified side panel that appears on hover. + + Hovering over the image shows a rectangle indicator and a zoom panel + to the right displaying the magnified region — the classic e-commerce + product zoom pattern. + + Examples: + ```python + from wigglystuff import HoverZoom + + # From a file path + widget = HoverZoom("photo.jpg", zoom_factor=3.0) + + # From a matplotlib figure + import matplotlib.pyplot as plt + fig, ax = plt.subplots() + ax.scatter(x, y, s=5, alpha=0.5) + widget = HoverZoom(fig, zoom_factor=4.0) + ``` + """ + + _esm = Path(__file__).parent / "static" / "hover-zoom.js" + _css = Path(__file__).parent / "static" / "hover-zoom.css" + + image = traitlets.Unicode("").tag(sync=True) + zoom_factor = traitlets.Float(3.0).tag(sync=True) + width = traitlets.Int(500).tag(sync=True) + height = traitlets.Int(0).tag(sync=True) + + def __init__( + self, + image: Optional[Union[str, Path, Any]] = None, + *, + zoom_factor: float = 3.0, + width: int = 500, + height: int = 0, + ): + """Create a HoverZoom widget. + + Args: + image: Image source — matplotlib figure, file path, URL, PIL Image, + bytes, or base64 string. + zoom_factor: Magnification level for the zoom panel. + width: Display width of the source image in pixels. + height: Display height in pixels (0 = auto, preserve aspect ratio). + """ + super().__init__() + self.zoom_factor = zoom_factor + self.width = width + self.height = height + + if image is not None: + # Detect matplotlib figures by checking for savefig + if hasattr(image, "savefig"): + self.image = fig_to_base64(image) + else: + pil_image = input_to_pil(image) + if pil_image is not None: + self.image = pil_to_base64(pil_image) + + def get_pil(self): + """Return the current image as a PIL Image.""" + if not self.image: + return None + return base64_to_pil(self.image) diff --git a/wigglystuff/static/hover-zoom.css b/wigglystuff/static/hover-zoom.css new file mode 100644 index 00000000..31792de7 --- /dev/null +++ b/wigglystuff/static/hover-zoom.css @@ -0,0 +1,55 @@ +.hover-zoom-wrapper { + display: inline-flex; + align-items: flex-start; + gap: 8px; + position: relative; + color-scheme: light dark; + --hz-rect-bg: rgba(255, 255, 255, 0.25); + --hz-rect-border: rgba(0, 0, 0, 0.4); + --hz-panel-border: rgba(0, 0, 0, 0.15); + --hz-panel-shadow: 0 2px 8px rgba(0, 0, 0, 0.12); +} + +.dark .hover-zoom-wrapper, +.dark-theme .hover-zoom-wrapper, +[data-theme="dark"] .hover-zoom-wrapper { + --hz-rect-bg: rgba(255, 255, 255, 0.2); + --hz-rect-border: rgba(255, 255, 255, 0.6); + --hz-panel-border: rgba(255, 255, 255, 0.2); + --hz-panel-shadow: 0 2px 8px rgba(0, 0, 0, 0.4); +} + +.hover-zoom-source { + position: relative; + display: inline-block; + cursor: crosshair; + flex-shrink: 0; +} + +.hover-zoom-img { + display: block; + user-select: none; + -webkit-user-select: none; +} + +.hover-zoom-rect { + display: none; + position: absolute; + background: var(--hz-rect-bg); + border: 2px solid var(--hz-rect-border); + pointer-events: none; + box-sizing: border-box; +} + +.hover-zoom-rect--pinned { + border-style: dashed; +} + +.hover-zoom-panel { + display: none; + flex-shrink: 0; + border: 1px solid var(--hz-panel-border); + box-shadow: var(--hz-panel-shadow); + background-repeat: no-repeat; + background-color: transparent; +} diff --git a/wigglystuff/static/hover-zoom.js b/wigglystuff/static/hover-zoom.js new file mode 100644 index 00000000..0a43d919 --- /dev/null +++ b/wigglystuff/static/hover-zoom.js @@ -0,0 +1,142 @@ +function render({ model, el }) { + const wrapper = document.createElement("div"); + wrapper.classList.add("hover-zoom-wrapper"); + + const sourceContainer = document.createElement("div"); + sourceContainer.classList.add("hover-zoom-source"); + + const img = document.createElement("img"); + img.classList.add("hover-zoom-img"); + img.draggable = false; + + const rect = document.createElement("div"); + rect.classList.add("hover-zoom-rect"); + + const zoomPanel = document.createElement("div"); + zoomPanel.classList.add("hover-zoom-panel"); + + sourceContainer.appendChild(img); + sourceContainer.appendChild(rect); + wrapper.appendChild(sourceContainer); + wrapper.appendChild(zoomPanel); + el.appendChild(wrapper); + + let pinned = false; + + function updateImage() { + const src = model.get("image"); + img.src = src || ""; + zoomPanel.style.backgroundImage = src ? `url(${src})` : "none"; + } + + function updateSize() { + const w = model.get("width"); + const h = model.get("height"); + img.style.width = w + "px"; + img.style.height = h > 0 ? h + "px" : "auto"; + sourceContainer.style.width = w + "px"; + } + + function updateZoom() { + const zf = model.get("zoom_factor"); + const imgW = img.naturalWidth || img.offsetWidth; + const imgH = img.naturalHeight || img.offsetHeight; + zoomPanel.style.backgroundSize = (imgW * zf) + "px " + (imgH * zf) + "px"; + } + + function layoutPanel() { + const displayH = img.offsetHeight || img.naturalHeight || 300; + zoomPanel.style.width = displayH + "px"; + zoomPanel.style.height = displayH + "px"; + updateZoom(); + } + + function positionZoom(mouseX, mouseY) { + const bounds = img.getBoundingClientRect(); + const imgW = bounds.width; + const imgH = bounds.height; + + const zf = model.get("zoom_factor"); + const panelW = zoomPanel.offsetWidth; + const panelH = zoomPanel.offsetHeight; + + const rectW = panelW / zf; + const rectH = panelH / zf; + + let rectLeft = mouseX - rectW / 2; + let rectTop = mouseY - rectH / 2; + rectLeft = Math.max(0, Math.min(rectLeft, imgW - rectW)); + rectTop = Math.max(0, Math.min(rectTop, imgH - rectH)); + + rect.style.width = rectW + "px"; + rect.style.height = rectH + "px"; + rect.style.left = rectLeft + "px"; + rect.style.top = rectTop + "px"; + + const ratioX = rectLeft / imgW; + const ratioY = rectTop / imgH; + const bgW = imgW * zf; + const bgH = imgH * zf; + + zoomPanel.style.backgroundPosition = -(ratioX * bgW) + "px " + -(ratioY * bgH) + "px"; + zoomPanel.style.backgroundSize = bgW + "px " + bgH + "px"; + } + + function showZoom() { + rect.style.display = "block"; + zoomPanel.style.display = "block"; + layoutPanel(); + } + + function hideZoom() { + rect.style.display = "none"; + zoomPanel.style.display = "none"; + } + + img.onload = function () { + layoutPanel(); + }; + + sourceContainer.addEventListener("mouseenter", function () { + showZoom(); + }); + + sourceContainer.addEventListener("mouseleave", function () { + if (!pinned) { + hideZoom(); + } + }); + + sourceContainer.addEventListener("mousemove", function (e) { + if (pinned) return; + const bounds = img.getBoundingClientRect(); + positionZoom(e.clientX - bounds.left, e.clientY - bounds.top); + }); + + // Double-click to pin the zoom at the current position + sourceContainer.addEventListener("dblclick", function (e) { + e.preventDefault(); + pinned = true; + rect.classList.add("hover-zoom-rect--pinned"); + showZoom(); + const bounds = img.getBoundingClientRect(); + positionZoom(e.clientX - bounds.left, e.clientY - bounds.top); + }); + + // Single click to unpin and resume following + sourceContainer.addEventListener("click", function (e) { + if (!pinned) return; + pinned = false; + rect.classList.remove("hover-zoom-rect--pinned"); + }); + + updateImage(); + updateSize(); + + model.on("change:image", updateImage); + model.on("change:width", function () { updateSize(); layoutPanel(); }); + model.on("change:height", function () { updateSize(); layoutPanel(); }); + model.on("change:zoom_factor", updateZoom); +} + +export default { render }; From 0b7bd21b691c6388346f7b2bf7e5b3ad1262deb9 Mon Sep 17 00:00:00 2001 From: koaning Date: Tue, 24 Mar 2026 15:26:15 +0100 Subject: [PATCH 2/2] Replace get_pil with get_pil_zoom that returns the zoomed crop region Co-Authored-By: Claude Opus 4.6 --- agents.md | 2 +- wigglystuff/hover_zoom.py | 14 +++++++++++--- wigglystuff/static/hover-zoom.js | 6 ++++++ 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/agents.md b/agents.md index f7ea9d46..26f13970 100644 --- a/agents.md +++ b/agents.md @@ -35,7 +35,7 @@ syncs back to Python. | ThreeWidget | `wigglystuff.three_widget.ThreeWidget` | `data`, `width`, `height`, `show_grid`, `show_axes`, `dark_mode`, `axis_labels`, `animate_updates`, `animation_duration_ms` | 3D scatter plot for point clouds | | WebcamCapture | `wigglystuff.webcam_capture.WebcamCapture` | `image_base64`, `capturing`, `interval_ms`, `facing_mode` | Webcam preview with snapshot capture | | GamepadWidget | `wigglystuff.gamepad.GamepadWidget` | `axes`, `current_button_press`, `dpad_*`, `current_timestamp` | Streams browser Gamepad API events | -| HoverZoom | `wigglystuff.hover_zoom.HoverZoom` | `image`, `zoom_factor`, `width`, `height` | Image hover zoom with magnified side panel | +| HoverZoom | `wigglystuff.hover_zoom.HoverZoom` | `image`, `zoom_factor`, `width`, `height`, `_crop` | Image hover zoom with magnified side panel | | KeystrokeWidget | `wigglystuff.keystroke.KeystrokeWidget` | `last_key` | Captures the latest keypress w/ modifiers | | WebkitSpeechToTextWidget | `wigglystuff.talk.WebkitSpeechToTextWidget` | `transcript`, `listening`, `trigger_listen` | WebKit speech recognition bridge | | DriverTour | `wigglystuff.driver_tour.DriverTour` | `steps`, `auto_start`, `show_progress`, `active`, `current_step` | Guided product tours via Driver.js | diff --git a/wigglystuff/hover_zoom.py b/wigglystuff/hover_zoom.py index ea93c5e8..06d618e8 100644 --- a/wigglystuff/hover_zoom.py +++ b/wigglystuff/hover_zoom.py @@ -41,6 +41,7 @@ class HoverZoom(anywidget.AnyWidget): zoom_factor = traitlets.Float(3.0).tag(sync=True) width = traitlets.Int(500).tag(sync=True) height = traitlets.Int(0).tag(sync=True) + _crop = traitlets.List(traitlets.Float(), [0.0, 0.0, 1.0, 1.0]).tag(sync=True) def __init__( self, @@ -73,8 +74,15 @@ def __init__( if pil_image is not None: self.image = pil_to_base64(pil_image) - def get_pil(self): - """Return the current image as a PIL Image.""" + def get_pil_zoom(self): + """Return the currently zoomed region as a PIL Image. + + Returns the cropped portion of the image that is visible in the + zoom panel. Returns ``None`` if no image is set. + """ if not self.image: return None - return base64_to_pil(self.image) + img = base64_to_pil(self.image) + x0_r, y0_r, x1_r, y1_r = self._crop + w, h = img.size + return img.crop((int(x0_r * w), int(y0_r * h), int(x1_r * w), int(y1_r * h))) diff --git a/wigglystuff/static/hover-zoom.js b/wigglystuff/static/hover-zoom.js index 0a43d919..1008bdfd 100644 --- a/wigglystuff/static/hover-zoom.js +++ b/wigglystuff/static/hover-zoom.js @@ -75,11 +75,17 @@ function render({ model, el }) { const ratioX = rectLeft / imgW; const ratioY = rectTop / imgH; + const ratioW = rectW / imgW; + const ratioH = rectH / imgH; const bgW = imgW * zf; const bgH = imgH * zf; zoomPanel.style.backgroundPosition = -(ratioX * bgW) + "px " + -(ratioY * bgH) + "px"; zoomPanel.style.backgroundSize = bgW + "px " + bgH + "px"; + + // Sync crop region to Python as [x0, y0, x1, y1] ratios + model.set("_crop", [ratioX, ratioY, ratioX + ratioW, ratioY + ratioH]); + model.save_changes(); } function showZoom() {