feat: decouple Matplotlib render resolution (DPI) from display size (#9144)

## 📝 Summary

Closes #9124

This PR decouples the internal rendering resolution (DPI) of Matplotlib
figures from their display size in the marimo notebook.

The fundamental principle is that DPI should control image quality
(sharpness), not the physical display size.

Previously, increasing `fig.dpi` to achieve a sharper image caused the
plot to expand linearly, often breaking the notebook layout. This change
ensures that figures maintain a consistent display size based on a 100
DPI reference (Matplotlib's default), regardless of the rendering DPI.

## Changes

- **Simplified Rendering Logic**: Removed the hardcoded "retina" logic
(`*2` DPI and `//2` dimensions).
- **Dynamic Scaling**: The rendering now respects the figure's actual
DPI setting.
- **Metadata Normalization**: Display dimensions (width/height) sent to
the frontend are now scaled by `dpi / 100`. This ensures that a figure
with a given `figsize` occupies the same space in the notebook even if
the DPI is increased for higher quality.
- **Enhanced Testing**: Added parameterized tests in
`tests/_output/formatters/test_matplotlib.py` to verify that:
    1. The actual PNG pixel count increases with DPI.
    2. The metadata display size remains consistent regardless of DPI.

## Verification

The following image demonstrates the fix:

<img width="400"
src="https://github.com/user-attachments/assets/4cacf0f4-f94a-4f9f-9926-2ab84d27f832"
/>

- **Top**: `fig.dpi = 20` (Low resolution, correct display size)
- **Middle**: `fig.dpi = 300` (High resolution, **same display size**)
- **Bottom**: `savefig.format = "svg"` (Consistent behavior with SVG)

As shown, the display size remains stable even when the DPI is changed
significantly, allowing users to control image quality without affecting
the notebook layout.



## 📋 Pre-Review Checklist
<!-- These checks need to be completed before a PR is reviewed -->

- [x] For large changes, or changes that affect the public API: this
change was discussed or approved through an issue, on
[Discord](https://marimo.io/discord?ref=pr), or the community
[discussions](https://github.com/marimo-team/marimo/discussions) (Please
provide a link if applicable).
- [ ] Any AI generated code has been reviewed line-by-line by the human
PR author, who stands by it.
- [x] Video or media evidence is provided for any visual changes
(optional). <!-- PR is more likely to be merged if evidence is provided
for changes made -->

## ✅ Merge Checklist

- [x] I have read the [contributor
guidelines](https://github.com/marimo-team/marimo/blob/main/CONTRIBUTING.md).
- [ ] Documentation has been updated where applicable, including
docstrings for API changes.
- [x] Tests have been added for the changes made.

Author: daizutabi

frontend/src/components/editor/Output.tsx

@@ -263,7 +263,7 @@ const MimeBundleOutputRenderer: React.FC<{
   const { mode } = useAtomValue(viewStateAtom);
   const appView = mode === "present" || mode === "read";
 
-  // Extract metadata if present (e.g., for retina image rendering)
+  // Extract metadata if present (e.g., to maintain a constant display size regardless of DPI/PPI)
   const metadata = mimebundle[METADATA_KEY];
 
   // Filter out metadata from the mime entries and type narrow

marimo/_output/mpl.py

@@ -83,11 +83,8 @@ def _render_figure_mimebundle(
         data_url = build_data_url(mimetype="image/svg+xml", data=plot_bytes)
         return "image/svg+xml", data_url
 
-    # Get current DPI and double it for retina display (like Jupyter)
-    original_dpi = fig.figure.dpi  # type: ignore[attr-defined]
-    retina_dpi = original_dpi * 2
-
-    fig.figure.savefig(buf, format="png", bbox_inches="tight", dpi=retina_dpi)  # type: ignore[attr-defined]
+    dpi = fig.figure.dpi
+    fig.figure.savefig(buf, format="png", bbox_inches="tight", dpi=dpi)  # type: ignore[attr-defined]
 
     png_bytes = buf.getvalue()
     plot_bytes = base64.b64encode(png_bytes)
@@ -98,12 +95,15 @@ def _render_figure_mimebundle(
     try:
         # Extract dimensions from the PNG
         width, height = _extract_png_dimensions(png_bytes)
+        # Normalize to a fixed 100 DPI reference for consistent display size
+        # https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.html
+        factor = dpi / 100
         mimebundle = {
             "image/png": data_url,
             METADATA_KEY: {
                 "image/png": {
-                    "width": width // 2,
-                    "height": height // 2,
+                    "width": round(width / factor),
+                    "height": round(height / factor),
                 }
             },
         }

tests/_output/formatters/test_matplotlib.py

@@ -84,23 +84,25 @@ def _extract_png_dimensions(data_url: str) -> tuple[int, int]:
 
 
 @pytest.mark.skipif(not HAS_MPL, reason="optional dependencies not installed")
-async def test_matplotlib_retina_rendering(
-    executing_kernel: Kernel, exec_req: ExecReqProvider
+@pytest.mark.parametrize("dpi", [72, 300])
+async def test_matplotlib_image_resolution_respects_dpi(
+    executing_kernel: Kernel,
+    exec_req: ExecReqProvider,
+    dpi: int,
 ) -> None:
-    """Test that matplotlib figures are rendered at 2x DPI for retina displays."""
+    """Test that the actual image resolution (pixels) scales with DPI."""
     from marimo._output.formatters.formatters import register_formatters
 
     register_formatters(theme="light")
 
     await executing_kernel.run(
         [
             exec_req.get(
-                """
+                f"""
                 import matplotlib.pyplot as plt
 
-                # Create a simple figure
-                fig, ax = plt.subplots(figsize=(4, 3))
-                ax.plot([1, 2, 3], [1, 2, 3])
+                # Create an empty figure (no content) to isolate DPI effects
+                fig = plt.figure(figsize=(4, 3), dpi={dpi})
 
                 # Get the formatted output
                 result = fig._mime_()
@@ -124,12 +126,13 @@ async def test_matplotlib_retina_rendering(
     png_data_url = mimebundle["image/png"]
     width, height = _extract_png_dimensions(png_data_url)
 
-    # Verify it's rendering at high DPI (should be significantly larger than
-    # the base figsize in pixels). At 2x DPI, a 4x3 inch figure should be
-    # at least 500x400 pixels (allowing for different base DPI values)
-    # The exact value depends on matplotlib's default DPI (can be 72, 90, 100, etc.)
-    assert width >= 500, f"Expected high-res width (>500px), got {width}"
-    assert height >= 350, f"Expected high-res height (>350px), got {height}"
+    # https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html
+    pad_inches = 0.1
+    calc_width = round((4 + 2 * pad_inches) * dpi)
+    calc_height = round((3 + 2 * pad_inches) * dpi)
+
+    assert calc_width - 5 < width < calc_width + 5
+    assert calc_height - 5 < height < calc_height + 5
 
     # Verify aspect ratio is preserved (4:3 ratio)
     aspect_ratio = width / height
@@ -140,23 +143,23 @@ async def test_matplotlib_retina_rendering(
 
 
 @pytest.mark.skipif(not HAS_MPL, reason="optional dependencies not installed")
-async def test_matplotlib_retina_metadata(
-    executing_kernel: Kernel, exec_req: ExecReqProvider
+@pytest.mark.parametrize("dpi", [72, 300])
+async def test_matplotlib_display_size_remains_constant(
+    executing_kernel: Kernel, exec_req: ExecReqProvider, dpi: int
 ) -> None:
-    """Test that matplotlib figures include proper width/height metadata."""
+    """Test that the display size in the notebook remains constant even if DPI changes."""
     from marimo._output.formatters.formatters import register_formatters
 
     register_formatters(theme="light")
 
     await executing_kernel.run(
         [
             exec_req.get(
-                """
+                f"""
                 import matplotlib.pyplot as plt
 
-                # Create a simple figure
-                fig, ax = plt.subplots(figsize=(4, 3))
-                ax.plot([1, 2, 3], [1, 2, 3])
+                # Create an empty figure (no content) to isolate DPI effects
+                fig = plt.figure(figsize=(4, 3), dpi={dpi})
                 result = fig._mime_()
                 """
             )
@@ -177,32 +180,28 @@ async def test_matplotlib_retina_metadata(
         "Metadata should include image/png dimensions"
     )
 
-    # Extract actual PNG dimensions
-    png_data_url = mimebundle_data["image/png"]
-    actual_width, actual_height = _extract_png_dimensions(png_data_url)
-
-    # Metadata dimensions should be half of actual (for retina display)
+    # Metadata dimensions should be figsize (4x3 inches) in 100 DPI.
     png_metadata = metadata["image/png"]
     assert "width" in png_metadata
     assert "height" in png_metadata
 
     metadata_width = png_metadata["width"]
     metadata_height = png_metadata["height"]
 
-    # Metadata should be approximately half the actual PNG dimensions
-    assert abs(metadata_width - actual_width // 2) <= 2, (
-        f"Metadata width {metadata_width} should be ~half of actual {actual_width}"
-    )
-    assert abs(metadata_height - actual_height // 2) <= 2, (
-        f"Metadata height {metadata_height} should be ~half of actual {actual_height}"
-    )
+    # https://matplotlib.org/stable/api/_as_gen/matplotlib.figure.Figure.savefig.html
+    pad_inches = 0.1
+    calc_width = round((4 + 2 * pad_inches) * 100)
+    calc_height = round((3 + 2 * pad_inches) * 100)
+
+    assert calc_width - 5 < metadata_width < calc_width + 5
+    assert calc_height - 5 < metadata_height < calc_height + 5
 
 
 @pytest.mark.skipif(not HAS_MPL, reason="optional dependencies not installed")
 async def test_matplotlib_backwards_compatibility(
     executing_kernel: Kernel, exec_req: ExecReqProvider
 ) -> None:
-    """Test that existing matplotlib code still works with retina rendering."""
+    """Test that existing matplotlib code still works with the new DPI rendering logic."""
     from marimo._output.formatters.formatters import register_formatters
 
     register_formatters(theme="light")