This looks interesting. Thanks for working on it.

Since I’m not into the topic I can dare to ask the stupid questions:

• Is it correct that an Artist and its blend mode define completely how they blend with “the background” I.e. all previously drawn artists? In particular, this does not depend on the blend mode of the other artists.
• Are all these blend modes parameter-less?

• Is it correct that an Artist and its blend mode define completely how they blend with “the background” I.e. all previously drawn artists? In particular, this does not depend on the blend mode of the other artists.

Yup, that is correct: the history of how that "background" was constructed has no bearing on how the next Artist is blended in using its specific blend mode.

It's also important to remember that that the "empty" background of an Axes is solid white, and thus not actually empty as far as these blend modes are concerned. For example, using "screen" to blend in an image on a truly empty background will just return the image, but on a white background will return solid white, which can make it look instead like the image call failed. That's why I turn off the face colors in my example above.

What I still need to investigate is how my changes interact with collections of Artists. A user may want "over" blending (the default) within the collection before using a different blend mode for the collection as a whole.

• Are all these blend modes parameter-less?

Yes. In principle, the transformation functions for the hue/saturation/color/luminosity operators could have more than one possibility, but in practice I think everyone has simply used the same functions for decades (as defined in the PDF specification).

This is pretty cool :-)

It's also important to remember that that the "empty" background of an Axes is solid white, and thus not actually empty as far as these blend modes are concerned. For example, using "screen" to blend in an image on a truly empty background will just return the image, but on a white background will return solid white, which can make it look instead like the image call failed. That's why I turn off the face colors in my example above.

What I still need to investigate is how my changes interact with collections of Artists. A user may want "over" blending (the default) within the collection before using a different blend mode for the collection as a whole.

Actually I suspect that another possibility is to want some nonstandard blending between multiple artists, then "over" blending of the result over the background.

In general I suspect this would be related to adding support for temporary, intermediate rendering buffers, which is also something that would be useful for other purposes e.g. contour label overplotting (#26971 (comment)).

By the way, I decided to rename "over" to "normal". That mode of blending is referred to as "normal" often enough, and it makes it readily apparent to users that it is the standard choice (and the default).

Yeah, I think you're right on not putting in a warning. The false positive of emitting a warning when someone legitimately wants to name an SVG group something totally reasonable like "overlay" is not worth mitigating the hypothetical confusion of someone mistakenly calling open_group() instead of open_blend_group(). When the group isn't blending as they desire, hopefully they pull up the docstring on the method they are calling and that will immediately reveal the error to them.

I've implemented two more Porter-Duff compositing operators – "source" and "clear" – for both Agg and Cairo backends, but I think "source" is too confusing of a name. Since "source" provides the similar behavior as a knockout group, I have renamed it "knockout" for blend_mode.

I've now implemented that a blend group can be an isolated group, a knockout group, both, or neither. Isolated groups are supported by all non-PS backends. Knockout groups are fully supported by only the PDF and PGF backends and partially supported by Agg and Cairo backends (cannot do non-isolated and knockout at the same time). If a knockout group is specified and the backend does not support it, the group will be rendered as non-knockout (in the images below, the panel on the right falls back to the panel to the left).

Agg

Top-right panel is not supported

Cairo

Top-right panel is not supported

SVG

Right column is not supported

PDF

All supported
bg.pdf

PGF

All supported
bg.pgf.pdf

Generating code

import matplotlib
#matplotlib.use('TkCairo')

import numpy as np

import matplotlib.pyplot as plt
from matplotlib.artist import Artist
from matplotlib.patches import Circle

class ArtistGroup(Artist):
    def __init__(self, artist_list, *, group_blend_mode=None, group_alpha=1, knockout=False):
        self._artist_list = artist_list
        self._group_blend_mode = group_blend_mode
        self._group_alpha = group_alpha
        self._knockout = knockout
        super().__init__()

    def draw(self, renderer):
        renderer.open_blend_group(self._group_blend_mode, alpha=self._group_alpha, knockout=self._knockout)
        for a in self._artist_list:
            if not a.is_transform_set():
                a.set_transform(self.get_transform())
            a.draw(renderer)
        renderer.close_blend_group()


fig, axs = plt.subplots(2, 2, figsize=(6, 6), layout='constrained')
fig.set_facecolor("none")

for i, group_blend_mode in enumerate([None, "normal"]):
    for j, knockout in enumerate([False, True]):
        axs[i, j].set_facecolor("none")
        axs[i, j].set_xlim(-1, 1)
        axs[i, j].set_ylim(-1, 1)
        axs[i, j].set_aspect("equal")

        axs[i, j].imshow(np.arange(20*20).reshape((20, 20)) % 19,
                      cmap='Spectral', extent=[-1, 1, -1, 1])

        left = Circle((-0.25, 0), 0.6, fc='c', alpha=0.75, blend_mode='multiply')
        right = Circle((0.25, 0), 0.6, fc='m', alpha=0.75, blend_mode='multiply')

        both = ArtistGroup([left, right], group_blend_mode=group_blend_mode, knockout=knockout)
        axs[i, j].add_artist(both)

axs[0, 0].set_title('non-knockout')
axs[0, 1].set_title('knockout')
axs[0, 0].set_ylabel('non-isolated')
axs[1, 0].set_ylabel('isolated')

plt.show()

Update: Now reverted, but I put the function at the bottom of this post in case someone in the future wants to give this approach another try

I had been hoping to use the blend modes and blend groups to fix the issue of visible grid lines of pcolormesh with the PDF backend, as worked so well for the Agg/Cairo backends (#31162 (comment)). However, nothing in that vein really panned out. Instead, an approach that works is to implement a RendererPdf.draw_quad_mesh() that takes advantage of the fact that the existing draw_gouraud_triangles() code already specifies each Gouraud triangle in a disconnected fashion, even for adjacent triangles. So, draw_quad_mesh() creates a Gouraud mesh where each triangle is flat in color and adjacent triangles can have different colors even at shared vertices.

I will actually likely revert this change because the alignment and edge aliasing is worse with this change, but it does get rid of the visible grid lines.

Before this PR

Figure_1-before.pdf

After this PR

Figure_1-after.pdf

Preserving the attempt for posterity:

    def draw_quad_mesh(self, gc, master_transform, meshWidth, meshHeight,
                       coordinates, offsets, offsetTrans, facecolors,
                       antialiased, edgecolors):
        # Use the fallback drawing of each quad as a path if edges are stroked
        if (edgecolors.size != 0 and edgecolors[0][3] != 0):
            super().draw_quad_mesh(gc, master_transform, meshWidth, meshHeight,
                                   coordinates, offsets, offsetTrans, facecolors,
                                   antialiased, edgecolors)
            return

        # Otherwise, leverage the Gouraud code path with each triangle having
        # three vertices of the same color, but common vertices of adjacent
        # triangles can have different colors

        if isinstance(coordinates, np.ma.MaskedArray):
            p = coordinates.data
        else:
            p = coordinates

        # TODO: adjust for offsets and offsetTrans

        p_a = p[:-1, :-1]
        p_b = p[:-1, 1:]
        p_c = p[1:, 1:]
        p_d = p[1:, :-1]
        triangles = np.concatenate([
            p_a, p_b, p_c,
            p_c, p_a, p_d,
        ], axis=2).reshape((-1, 3, 2))

        colors = np.repeat(facecolors, 6, axis=0).reshape((-1, 3, 4))
        empty = (colors[:, 0, 3] == 0)

        self.draw_gouraud_triangles(gc, triangles[~empty], colors[~empty],
                                    master_transform)

Ugh, trying to have a Cairo figure test is a disaster.

The Cairo bug with missing text is not limited to Windows, but I don't have a handle on the common thread (and there may be multiple issues at play).

From the CI:

From my own machines:

I have not yet tried to vary the installed versions, but I feel like there are other packages that matter or the precise way that cairo 1.18.4 was built matters.

Even setting aside the bug, the text is rendered slightly differently between the CI builds. And even ignoring all text-related discrepancies, the blending is a bit different on the edges between the macOS ARM builds and the Ubuntu builds. The three categories of builds are running different versions of libcairo, so the blending differences might be due to that, but that still inhibits a common image test.

Image diff between Ubuntu 22.04 and Ubuntu 24.04

Image diff between Ubuntu 22.04 and macOS arm64

I didn't know, but am not really surprised that cairo's exact rendering depends on the details of the build. Looks like the difference is mostly related to antialiasing, i.e. the colors in the "middle" of the overlaying patches still match, so perhaps 1) disabling antialiasing throughout may help (set_antialias(False) on the patches)?, or 2) instead of an image comparison test, the test could be to draw two partially overlapping squares, then extract the rgba buffer and simply test the rgba values for a pixel in the middle of the first square, for a pixel in the middle of the second square, and for a pixel in the overlaying region.
(Getting texts to match across versions is pretty much hopeless (I don't know if cairo picks up matplotlib's forced freetype version -- likely not?) and I would just get rid of them in the test images.)

Here is how I have decided to resolve the Cairo image test:

• Remove all text from the test image generated for Cairo. All other backends continue to test text.
• Use the macOS arm64 output as the reference image (zero tolerance) because it is the only category of CI builds that actually install the latest version of cairo (1.18.4)
• For the CI builds that run an older version of cairo (i.e., 1.16.0 or 1.18.0 running on Ubuntu), the non-text rendering discrepancies smell like bugs in Cairo rendering prior to 1.18.4, so I bump the tolerance up to 3 to account for them, and I think 3 is still low enough to be somewhat useful. For comparison the rendering difference when text is on the image is >18.

This PR is ready for comprehensive review! The remaining open question in my mind is whether the helper ArtistGroup class that I define on the documentation page for blend groups is appropriate and robust enough to live in the library proper. But, that decision could also be put off until the blend-group functionality has been out in the wild for a while.

Here's an example of using the "screen" blend mode to composite two images of the Sun at different wavelengths (171 angstroms in yellow, 211 angstroms in purple):

call nit about docs: Can you combine the examples into a "blending alpha" user guide entry under color. Alpha is introduced in the colors explanation so I think goes under the "colors" category.

I have relocated the two documentation pages to under "Colors" in the user guide, and linked to the blend-modes page from the existing description of normal alpha blending.

Also, the conclusion at yesterday's dev meeting was that – for this PR – the helper class (ArtistGroup) can live on just the documentation page rather than being moved to the library proper. The thinking is that there ought to be a future discussion of the requirements and design of a fully realized "compound artist" class, and how that may intersect with or replace the existing Container class, but that is all beyond the scope of this PR.

As a nudge for reviewer attention on this PR, I'll point out that the added documentation page for blend modes now starts with this simple example to illustrate the benefit of non-normal blending:

import matplotlib.pyplot as plt
from matplotlib.patches import Circle

fig, ax = plt.subplots(figsize=(6, 3), layout='constrained')

ax.text(1.5, 1.3, '"normal" blend mode', ha='center')
ax.add_patch(Circle((1, 0), 1, color='c', ec='none'))
ax.add_patch(Circle((2, 0), 1, color='m', ec='none'))
ax.add_patch(Circle((1.5, -0.87), 1, color='y', ec='none'))

ax.text(5.5, 1.3, '"multiply" blend mode', ha='center')
ax.add_patch(Circle((5, 0), 1, color='c', ec='none', blend_mode='multiply'))
ax.add_patch(Circle((6, 0), 1, color='m', ec='none', blend_mode='multiply'))
ax.add_patch(Circle((5.5, -0.87), 1, color='y', ec='none', blend_mode='multiply'))

ax.set_xlim(-0.2, 7.2)
ax.set_ylim(-1.9, 1.2)
ax.set_aspect('equal')
ax.axis('off')

I am 👍🏻 on this conceptually but have not reviewed the code.

I've confirmed: if a blending use case is not supported by a vector backend but is supported by the Agg backend, then turning on rasterization can be a workaround assuming that the fixed resolution of the output is acceptable. This even works for the PS backend as long as alpha is 1 everywhere.

This means the support tables could be written as:

✅ = supported, 🟡 = supported through rasterization, ❌ = not supported

Updates over the past two weeks:

• In the documentation, I now discuss rasterization as an option to achieve blending results that are not natively supported by the particular vector backend, which greatly reduces the number of ❌ in the support tables. I also added figure tests for rasterization.
• I chose better colors for the blend-groups documentation so that it is easier to see the differences between the options.
• For non-isolated knockout blend groups (which not supported in general by Agg, which is a problem for the rendered documentation), I now show a workaround that can be used for Agg – and hence can be shown in the rendered documentation – if all the artists in the group have the same blend mode.
• Buried in the thread above, I noted that sometimes the edges of two adjacent contour regions are not exactly coincident. I tracked that down to a snapping-related bug that is fixed by Fix a bug of ignoring the closing path segment when automatically determining whether to snap #32018.