|
1 | 1 | """ |
2 | | -================== |
3 | | -Rasterization Demo |
4 | | -================== |
| 2 | +================================= |
| 3 | +Rasterization for vector graphics |
| 4 | +================================= |
5 | 5 |
|
6 | | -Rasterization is a method where an image described in a vector graphics |
7 | | -format is being converted into a raster image (pixels). |
| 6 | +Rasterization converts vector graphics into a raster image (pixels). |
8 | 7 |
|
9 | 8 | Individual artists can be rasterized for saving to a vector backend |
10 | 9 | such as PDF, SVG, or PS as embedded images. This can be useful to |
11 | 10 | reduce the file size of large artists, while maintaining the |
12 | 11 | advantages of vector graphics for other artists such as the axes |
13 | | -and annotations. For instance a complicated `~.Axes.pcolormesh` or |
| 12 | +and texts. For instance a complicated `~.Axes.pcolormesh` or |
14 | 13 | `~.Axes.contourf` can be made significantly simpler by rasterizing. |
15 | | -Note that the size and resolution of the rasterized artist is |
16 | | -controlled by its physical size and the value of the ``dpi`` kwarg |
17 | | -passed to `~.Figure.savefig`. |
| 14 | +
|
| 15 | +Rasterization is disabled by default. There are two ways to enable it, which |
| 16 | +can also be combined: |
| 17 | +
|
| 18 | +- Set `~.Artist.set_rasterized` on individual artists, or use the keyword |
| 19 | + argument *rasterized* when creating the artist. |
| 20 | +- Set `.Axes.set_rasterization_zorder` to rasterize all artists with a zorder |
| 21 | + less than the given value. |
| 22 | +
|
| 23 | +The storage size and the resolution of the rasterized artist is determined by |
| 24 | +its physical size and the value of the ``dpi`` parameter passed to |
| 25 | +`~.Figure.savefig`. |
| 26 | +
|
| 27 | +.. note:: |
| 28 | +
|
| 29 | + The image of this example shown in the HTML documentation is not a vector |
| 30 | + graphics. Therefore, it cannot illustrate the rasterization effect. Please |
| 31 | + run this example locally and check the generated graphics files. |
| 32 | +
|
18 | 33 | """ |
19 | 34 |
|
20 | 35 | import numpy as np |
|
27 | 42 | xx = x*np.cos(theta) - y*np.sin(theta) # rotate x by -theta |
28 | 43 | yy = x*np.sin(theta) + y*np.cos(theta) # rotate y by -theta |
29 | 44 |
|
30 | | -# Plot the rasterized and non-rasterized plot |
31 | 45 | fig, ((ax1, ax2), (ax3, ax4)) = plt.subplots(2, 2, constrained_layout=True) |
32 | 46 |
|
33 | | -# Create a pseudocolor non-rastertized plot with a non-regular rectangular grid |
| 47 | +# pcolormesh without rasterization |
34 | 48 | ax1.set_aspect(1) |
35 | 49 | ax1.pcolormesh(xx, yy, d) |
36 | 50 | ax1.set_title("No Rasterization") |
37 | 51 |
|
38 | | -# Create a pseudocolor rastertized plot with a non-regular rectangular grid |
| 52 | +# pcolormesh with rasterization; enabled by keyword argument |
39 | 53 | ax2.set_aspect(1) |
40 | 54 | ax2.set_title("Rasterization") |
41 | 55 | m = ax2.pcolormesh(xx, yy, d, rasterized=True) |
42 | 56 |
|
43 | | -# Create a pseudocolor non-rastertized plot with a non-regular rectangular |
44 | | -# grid and an overlapped "Text" |
| 57 | +# pcolormesh with an overlaid text without rasterization |
45 | 58 | ax3.set_aspect(1) |
46 | 59 | ax3.pcolormesh(xx, yy, d) |
47 | 60 | ax3.text(0.5, 0.5, "Text", alpha=0.2, |
48 | 61 | va="center", ha="center", size=50, transform=ax3.transAxes) |
49 | 62 | ax3.set_title("No Rasterization") |
50 | 63 |
|
51 | | -# Create a pseudocolor rastertized plot with a non-regular rectangular |
52 | | -# grid and an overlapped "Text" |
| 64 | +# pcolormesh with an overlaid text without rasterization; enabled by zorder. |
| 65 | +# Setting the rasterization zorder threshold to 0 and a negative zorder on the |
| 66 | +# pcolormesh rasterizes it. All artists have a non-negative zorder by default, |
| 67 | +# so they (e.g. the text here) are not affected. |
53 | 68 | ax4.set_aspect(1) |
54 | | -m = ax4.pcolormesh(xx, yy, d, zorder=-20) |
55 | | -ax4.text(0.5, 0.5, "Text", alpha=0.2, zorder=-15, |
| 69 | +m = ax4.pcolormesh(xx, yy, d, zorder=-10) |
| 70 | +ax4.text(0.5, 0.5, "Text", alpha=0.2, |
56 | 71 | va="center", ha="center", size=50, transform=ax4.transAxes) |
57 | | -# Set zorder value below which artists will be rasterized |
58 | | -ax4.set_rasterization_zorder(-10) |
| 72 | +ax4.set_rasterization_zorder(0) |
59 | 73 | ax4.set_title("Rasterization z$<-10$") |
60 | | -# ax2.title.set_rasterized(True) # should display a warning |
61 | 74 |
|
62 | 75 | # Save files in pdf and eps format |
63 | 76 | plt.savefig("test_rasterization.pdf", dpi=150) |
|
66 | 79 | if not plt.rcParams["text.usetex"]: |
67 | 80 | plt.savefig("test_rasterization.svg", dpi=150) |
68 | 81 | # svg backend currently ignores the dpi |
| 82 | + |
| 83 | +############################################################################# |
| 84 | +# |
| 85 | +# ------------ |
| 86 | +# |
| 87 | +# References |
| 88 | +# """""""""" |
| 89 | +# |
| 90 | +# The use of the following functions, methods, classes and modules is shown |
| 91 | +# in this example: |
| 92 | + |
| 93 | +import matplotlib |
| 94 | +matplotlib.artist.Artist.set_rasterized |
| 95 | +matplotlib.axes.Axes.set_rasterization_zorder |
| 96 | +matplotlib.axes.Axes.pcolormesh |
| 97 | +matplotlib.pyplot.pcolormesh |
0 commit comments