[ENH]: mutation_aspect for Round BoxStyle type

[tricarbonate]

Problem

I was trying to make a bar chart with rounded corners, which necessitates using FancyBBoxPatch. However, I would have expected rounded corners to be isotropic by default.

Example showing default behavior and expected behavior (bar on the right):

import matplotlib.pyplot as plt
from matplotlib.patches import FancyBboxPatch, BoxStyle

def add_bar(ax, x, y, w, h, mutation_aspect=1):
    patch = FancyBboxPatch(
        (x, y),
        w,
        h,
        boxstyle=BoxStyle("Round", pad=0, rounding_size=w / 2),
        linewidth=0,
        facecolor="C0",
        mutation_aspect=mutation_aspect,
    )
    ax.add_patch(patch)


fig, ax = plt.subplots(figsize=(10, 5))


x, y, w, h = 0.3, 0, 0.18, 1

# Left: default mutation_aspect=1 (shows issue)
add_bar(ax, x, y, w, h)

# Right: using 1/ax._get_aspect_ratio()
add_bar(ax, x + 0.3, y, w, h, 1 / ax._get_aspect_ratio())

plt.tight_layout()
plt.savefig("reproduce.png", dpi=220)
plt.show()

which gave:

The solution uses private API (ax._get_aspect_ratio()) because ax.get_aspect() returns "auto".

I'm guessing changing the default behavior is not possible for backward compatibility, so my question is: Would an opt-in auto mode for mutation_aspect be acceptable to ensure isotropic rounding?

The same question applies to other BoxStyle types.

Proposed solution

An opt-in auto mode for mutation_aspect (for example passing mutation_aspect="auto") which changes default behavior and sets the mutation_aspect value to 1 / ax._get_aspect_ratio() internally in the FancyBboxPatch class

[Farzah11]

I’d like to work on this.
My plan is to add support for mutation_aspect="auto" and compute the display-space aspect ratio using the axes’ public transform (transData), avoiding reliance on _get_aspect_ratio().
Please let me know if this approach aligns with expectations.

[timhoffm]

I'm not clear whether this is solvable with an out-of-the-box solution in matplotlib. The core issue is that everything happens in "box" coordinates, here the data coordinates, and they are asymmetric on screen if the axes aspect is != 1.

The workaround is to set the mutation_aspect to the inverse of the axes aspect ratio.

It may work to resolve the aspect dynamically. That is something to be investigeated.

The other aspect is the public API. mutation_aspect="auto" feels too generic and vague. "inverse-aspect" would be technical correct but not quite user friendly. Maybe something like "screen-equal" / "screen-proportional" or similar.

@Farzah11 you may work on this. However, this is not clearly defined and may have obstacles on its way (up to the decision that it may not be reasonable to integrate this at all).

[Farzah11]

Thank you for the detailed explanation and guidance on this issue. Given the current complexity and open questions around API design, I will focus on other issues for now, but I’m excited to continue contributing to the project.

[DevarshShroff]

I’d like to take this issue and get familiar with the repo.

The distortion happens because FancyBboxPatch.get_path() stretches the box vertically to fit your graph, but BoxStyle.Round applies the same rounding math to both sides as if they were equal. On "auto" aspect plots, the display scaling is uneven, so the fixed mutation_aspect fails to keep the corners circular. Basically, the function reshapes the box, but the rounding tool doesn't account for that stretching, leaving you with lopsided corners.

Proposed approach: add an opt-in mode like mutation_aspect="auto" for FancyBboxPatch. When set, compute an aspect correction from the owning Axes (e.g. 1 / ax._get_aspect_ratio() or an equivalent calculation) at path generation time, so rounding becomes isotropic in display space without changing the default behavior for existing code.

I can follow up with a PR adding the API, docs, and a test (likely an image comparison or a display-space geometry check) demonstrating that "auto" produces isotropic rounding under a non-square axes/figure configuration.