contourf workaround

Start in lib/iris/plot.py at the contourf workaround around lines 1134–1185, then review test_mapping.py::TestMappingSubRegion::test_simple and the linked Matplotlib pull request. Compare the current and no-workaround PDF examples, including rasterized output. Done means an agreed workaround policy is implemented with coverage for the relevant rendering behavior and user-facing guidance where needed.

📰 Custom Issue

iplt.contourf has a longstanding workaround to improve the look of antialiased plots.
https://github.com/SciTools/iris/blob/cefe4b78bc97d7b204551d597e19c75d9ebca19e/lib/iris/plot.py#L1134-L1185

I believe https://github.com/matplotlib/matplotlib/pull/32256 will make this workaround redundant for its stated purpose from Matplotlib v3.12 🎉

However, the workaround also affects plots saved to pdf. Adapting the code from test_mapping.py::TestMappingSubRegion::test_simple

import cartopy.crs as ccrs
import iris
import iris.plot as iplt
import matplotlib.pyplot as plt


cube = iris.load_cube('[path-to-iris-test-data]/test_data/PP/aPProt1/rotatedMHtimecube.pp')
cube = cube[0][::10][::10]

plt.figure(layout='constrained')

plt.subplot(221)
plt.title("Default")
iplt.contourf(cube)
plt.gca().coastlines("110m")

# Second sub-plot
plt.subplot(222, projection=ccrs.Mollweide(central_longitude=120))
plt.title("Molleweide")
iplt.contourf(cube)
plt.gca().coastlines("110m")

# Third sub-plot (the projection part is redundant, but a useful
# test none-the-less)
ax = plt.subplot(223, projection=iplt.default_projection(cube))
plt.title("Native")
iplt.contour(cube)
ax.coastlines("110m")

# Fourth sub-plot
ax = plt.subplot(2, 2, 4, projection=ccrs.PlateCarree())
plt.title("PlateCarree")
iplt.contourf(cube)
ax.coastlines("110m")

plt.savefig('test.pdf')

Running with current Iris main, we get

test_workaround.pdf

If I remove the workaround from Iris I get

test_no_workaround.pdf

Note that

• Without the workaround, we do see seams between the filled contours, which may be undesirable to some users.
• With the workaround, the right-hand plots show the ends of the added line contours, which also doesn't seem desirable.

As far as I understand image processing (not much), I do not think aliasing is relevant for pdf rendering. So I do not think it would make sense to keep the current workaround triggered by the antialiased keyword just for the pdf case (and possibly other vector graphics cases that I haven't checked).

Options

1. Factor out the workaround into a public function, so that pdf users who value the old behaviour can opt-in and apply it directly.
2. Encourage users to pass rasterized=True when they call contourf. Then the contours get converted to an image by the agg renderer (benefitting from matplotlib/32256) and the image is embedded into the pdf. This would mean users have to think about dpi to get a good quality. Here, I passed dpi=300 to savefig, and am using the branch from matplotlib/32256: test_no_workaround_rasterized.pdf
3. Both 1 and 2 - i.e. factor out the workaround and also document the pros and cons of the two options so users can make an informed choice.
4. Leave as it. I think this is the worst option because
   1. As stated above, having it triggered by the antialiased keyword doesn't really make sense for pdf
   2. We will be calling redundant code in many cases
   3. Silently creating and adding an extra artist to the axes just doesn't smell good in general
   4. Since our image tests all save to png, they likely wouldn't show any benefit of the workaround any more. We would at least need to find a different way to cover this.
5. Anything else? Presumably contourf plots made outside of Iris have either been living with the seams or using some other workaround for a long time.