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