Repository: sunpy/sunpy

Issue:
Add a gallery example showing how to use `mplcairo` for blending
`matplotlib` itself provides only alpha-based transparency for overlaying an image on top of another image, which can be quite limiting when attempting to produce nice-looking composite images.  `mplcairo` provides the usual variety of blending operators for image overlays, so we should have a tutorial for using `mplcairo`.  As far as our documentation goes, we have to configure the backend in the way needed to get Sphinx to do what we want.

Example example:
```python
import matplotlib; matplotlib.use("module://mplcairo.qt")
import matplotlib.pyplot as plt
from mplcairo import operator_t

import astropy.units as u

import sunpy.map
import sunpy.data.sample
from sunpy.coordinates import Helioprojective

a171 = sunpy.map.Map(sunpy.data.sample.AIA_171_IMAGE)
a131 = sunpy.map.Map(sunpy.data.sample.AIA_131_IMAGE)
with Helioprojective.assume_spherical_screen(a171.observer_coordinate):
    a131 = a131.reproject_to(a171.wcs)

fig = plt.figure()
ax = fig.add_subplot(projection=a171)

_ = a171.plot(clip_interval=(1, 99.9995)*u.percent)
im131 = a131.plot(clip_interval=(1, 99.95)*u.percent)

operator_t.SCREEN.patch_artist(im131)

ax.set_title('mplcairo composite using screen blending')

plt.show()
```
![mplcairo composite example](https://user-images.githubusercontent.com/991759/198420923-3db92465-bef9-4a0d-a5ec-913aed9e170b.png)


Discussion:
I've made additions to the /plotting folder, can someone check if this is correct?
I can't open a PR until my old PR is closed.
https://github.com/Satan-Claws/sunpy/blob/Satan-Claws-mplcairo/examples/plotting/mplcairo_blending.py
> I've made additions to the /plotting folder, can someone check if this is correct?

It looks like you've simply added brief comments to my example script above, so I imagine that it produces the correct output when run from a terminal.  Stuff that needs to be done:

- Add actual narrative to the example so that it is a tutorial.
- Ensure that Sphinx (on Read the Docs) renders the example correctly.  It's possible that a different Matplotlib backend needs to be selected for the documentation build, and we need to make sure that changing the backend here in this fashion doesn't muck up the rendering elsewhere in our documentation.

> I can't open a PR until my old PR is closed.

You can have more than one PR open at a time.  You already have this modification on a separate Git branch, so you simply need to create the PR from that branch instead of your `main` branch.
> > I've made additions to the /plotting folder, can someone check if this is correct?
> 
> It looks like you've simply added brief comments to my example script above, so I imagine that it produces the correct output when run from a terminal.  Stuff that needs to be done:
> 
> - Add actual narrative to the example so that it is a tutorial.
> - Ensure that Sphinx (on Read the Docs) renders the example correctly.  It's possible that a different Matplotlib backend needs to be selected for the documentation build, and we need to make sure that changing the backend here in this fashion doesn't muck up the rendering elsewhere in our documentation.
> 
> > I can't open a PR until my old PR is closed.
> 
> You can have more than one PR open at a time.  You already have this modification on a separate Git branch, so you simply need to create the PR from that branch instead of your `main` branch.

Okay I'll change the text to make it more of a tutorial. I'll check again if the display fits or not and then will create a PR
I'm sorry I wasn't able to work on this, I was attending a festival at home.
I've re-setup everything on WSL since mplcairo has issues working in Windows (in my virtual env, works fine at base). I'll install mplcairo, look at the docs made and will open a PR as soon as I make the correct tutorial.
@ayshih 
will it be enough if I add this same tutorial in examples/plotting
and maybe I can link this tutorial to docs in backend.
How is the gallery example coming in docs??

Resolving patch:
diff --git a/examples/plotting/mplcairo_plotting.py b/examples/plotting/mplcairo_plotting.py
new file mode 100644
--- /dev/null
+++ b/examples/plotting/mplcairo_plotting.py
@@ -0,0 +1,104 @@
+"""
+================================
+Blending maps using ``mplcairo``
+================================
+
+This example shows how to blend two maps using ``mplcairo``.
+
+``matplotlib`` by itself provides only alpha-based transparency for
+superimposing one image onto another, which can be restrictive when trying to
+create visually appealing composite images.
+`mplcairo <https://github.com/matplotlib/mplcairo>`__ is an enhancement for
+``matplotlib`` that provides support for
+`cairo's compositing operators <https://www.cairographics.org/operators/>`__,
+which include a wide range of
+`blend modes <https://en.wikipedia.org/wiki/Blend_modes>`__ for image overlays.
+
+.. note::
+
+   This example requires `mplcairo <https://github.com/matplotlib/mplcairo>`__
+   to be installed. Installation via ``pip`` will work in most cases, but you
+   may need to refer to
+   `OS-specific installation notes <https://github.com/matplotlib/mplcairo#installation>`__.
+"""
+
+###############################################################################
+# We need to tell ``matplotlib`` to use a backend from ``mplcairo``. The
+# backend formally needs to be set prior to importing ``matplotlib.pyplot``.
+# The ``mplcairo.qt`` GUI backend should work on Linux and Windows, but
+# you will need to use something different on macOS or Jupyter (see
+# ``mplcairo``'s `usage notes <https://github.com/matplotlib/mplcairo#use>`__).
+
+import matplotlib
+
+if matplotlib.get_backend() == "agg":
+    # This is the non-GUI backend for when building the documentation
+    matplotlib.use("module://mplcairo.base")
+else:
+    # This is a GUI backend that you would normally use
+    matplotlib.use("module://mplcairo.qt")
+
+###############################################################################
+# We can now import everything else.
+
+import matplotlib.pyplot as plt
+from mplcairo import operator_t
+
+import astropy.units as u
+
+import sunpy.data.sample
+import sunpy.map
+from sunpy.coordinates import Helioprojective
+
+###############################################################################
+# Let's load two maps for blending. We reproject the second map to the
+# coordinate frame of the first map for proper compositing, taking care to use
+# the :meth:`~sunpy.coordinates.Helioprojective.assume_spherical_screen`
+# context manager in order to preserve off-disk data.
+
+a171 = sunpy.map.Map(sunpy.data.sample.AIA_171_IMAGE)
+a131 = sunpy.map.Map(sunpy.data.sample.AIA_131_IMAGE)
+with Helioprojective.assume_spherical_screen(a171.observer_coordinate):
+    a131 = a131.reproject_to(a171.wcs)
+
+###############################################################################
+# Let's first plot the two maps individually.
+
+fig1 = plt.figure(figsize=(10, 4))
+ax1 = fig1.add_subplot(121, projection=a171)
+ax2 = fig1.add_subplot(122, projection=a131)
+
+a171.plot(axes=ax1, clip_interval=(1, 99.9995)*u.percent)
+a131.plot(axes=ax2, clip_interval=(1, 99.95)*u.percent)
+
+###############################################################################
+# We now plot the two maps on the same axes. If the plot were rendered at this
+# point, the second map would completely obscure the first map. We save the
+# ``matplotlib`` artist returned when plotting the second map (``im131``) for
+# future use.
+
+fig2 = plt.figure()
+ax = fig2.add_subplot(projection=a171)
+
+a171.plot(axes=ax, clip_interval=(1, 99.9995)*u.percent)
+im131 = a131.plot(axes=ax, clip_interval=(1, 99.95)*u.percent)
+
+# sphinx_gallery_defer_figures
+
+###############################################################################
+# We invoke the ``mplcairo`` operator for the
+# `screen blend mode <https://en.wikipedia.org/wiki/Blend_modes#Screen>`__
+# to modify the artist for the second map. The second map will
+# now be composited onto the first map using that blend mode.
+
+operator_t.SCREEN.patch_artist(im131)
+
+# sphinx_gallery_defer_figures
+
+###############################################################################
+# Finally, we set the title and render the plot.
+
+ax.set_title('mplcairo composite using screen blending')
+plt.show()
+
+# sphinx_gallery_thumbnail_number = 2


Test patch: