Add blend modes that maximize/minimize the pixel coverage - #32469

PR summary

This PR adds two new blend modes, which provide alternatives when alpha values represent pixel coverage rather than opacity. These blend modes are supported by only the Agg backend (and vector backends through rasterization).

Alpha is the combination of both opacity (i.e., transparency) and pixel coverage (the fraction of the pixel that is filled in with a color). In matplotlib, the alpha values along antialiased edges of patches is determined by calculating the pixel coverage. Importantly, once the alpha for a pixel is represented as a single number, there is no longer any geometric information about which part of the pixel is actually covered.

When alpha represents opacity, the existing blend modes have the desired output. When alpha represents pixel coverage, the behavior of the PDF blend modes is equivalent to assuming that the part of the source pixel that is covered and the part of the destination pixel that is covered are unrelated/independent. However, that assumption is broken when two patches intentionally share an edge:

• When the source patch is intended to exactly overlap the destination patch, and they both partially cover the result pixel and thus have the same alpha, ideally the result pixel would show only the source color. However, the assumption that the pixel coverages are independent means that part of the destination color leaks through.
• When the source patch is intended to be exactly contiguous to the destination patch, and their pixel coverages are complementary with alpha adding up to 1 (src.alpha + dest.alpha == 1), ideally the result pixel would have an alpha of 1. However, the assumption that the pixel coverages are independent means that the combined alpha is less than 1 (out.alpha = src.alpha + dest.alpha - src.alpha * dest.alpha < 1).

The two new blend modes in this PR are:

• "min cover": Minimize the amount of the destination pixel that is covered by the source pixel. The behavior is identical to the "plus" blend mode when src.alpha + dest.alpha <= 1, but it favors the source color when src.alpha + dest.alpha > 1.
• "max cover": Maximize the amount of the destination pixel that is covered by the source pixel. The behavior is similar to the "knockout" blend mode when src.alpha >= dest.alpha in that the source completely hides the destination.

This PR is an outgrowth of #32256, which currently uses the "plus" blend mode, but would behave better with the "min cover" blend mode in those situations when a collection of contiguous patches can also have overlapping of patches (e.g., as a result of a projection down from 3D space).

Example

• "max cover" avoids the color fringe when exactly overlapping patches (first row, fifth column).
• "min cover" – like "plus" – avoids the spurious faint line between adjacent patches (second row, third column) without the color adding of "plus" when the combined alpha is greater than 1 (third row, second and third columns).

import numpy as np

import matplotlib.pyplot as plt
from matplotlib.patches import Ellipse, Polygon, Rectangle

fig, axs = plt.subplots(1, 5, figsize=(7, 3), layout="constrained")
fig.set_facecolor("none")

for ax, blend_mode in zip(axs, ["normal", "plus", "min cover",
                                "knockout",  "max cover"]):
    ax.set_facecolor("none")

    # Exactly overlapping ellipses that share an antialiased edge
    ax.add_patch(Ellipse((0.5, 1.8), 1, 0.4, fc="m", ec="none"))
    ax.add_patch(Ellipse((0.5, 1.8), 1, 0.4, fc="y", ec="none", blend_mode=blend_mode))

    # Exactly adjacent patches with a shared antialised edge
    ax.add_patch(Polygon(np.array([[0, 0, 0.3, 0.9, 1], [1, 1.5, 1.1, 1.3, 1]]).T,
                 fc="purple", ec="none"))
    ax.add_patch(Polygon(np.array([[0, 0.3, 0.9, 1, 1], [1.5, 1.1, 1.3, 1, 1.5]]).T,
                 fc="purple", ec="none", blend_mode=blend_mode))

    # Overlapping rectangles with a variety of alpha combinations
    ax.add_patch(Rectangle((0, 0.7), 1, 0.1, fc="b", ec="none", alpha=1))
    ax.add_patch(Rectangle((0, 0.5), 1, 0.2, fc="b", ec="none", alpha=0.5))
    ax.add_patch(Rectangle((0, 0.1), 1, 0.2, fc="lime", ec="none", alpha=0.5))
    ax.add_patch(Rectangle((0, 0), 1, 0.1, fc="lime", ec="none", alpha=1))
    for rx, alpha in zip([0.1, 0.4, 0.7], [0.3, 0.5, 0.7]):
        ax.add_patch(Rectangle((rx, -0.1), 0.2, 1,
                     fc="b", ec="none", alpha=alpha, blend_mode=blend_mode))
    
    ax.set_title(blend_mode)
    ax.set_xlim(-.1, 1.1)
    ax.set_ylim(-.1, 2.1)
    ax.set_aspect("equal")
    ax.set_axis_off()

plt.show()

AI Disclosure

No AI was used

PR quality check

• Use an expressive title, e.g. "Fix title font property precedence"
• New and changed code is tested
• Plotting related features are demonstrated in an example
• New features and API changes have release notes
• Documentation complies with general and docstring guidelines