From cee2fb7f95b1227f800147caf862dbc7d130e781 Mon Sep 17 00:00:00 2001 From: Tim Hoffmann <2836374+timhoffm@users.noreply.github.com> Date: Fri, 11 Nov 2022 23:43:30 +0100 Subject: [PATCH] DOC: Clarify transparency in colors --- tutorials/colors/colors.py | 79 +++++++++++++++++++++++--------------- 1 file changed, 47 insertions(+), 32 deletions(-) diff --git a/tutorials/colors/colors.py b/tutorials/colors/colors.py index beeba7df3ead..224886c20483 100644 --- a/tutorials/colors/colors.py +++ b/tutorials/colors/colors.py @@ -1,8 +1,11 @@ """ ***************** -Specifying Colors +Specifying colors ***************** +Color formats +============= + Matplotlib recognizes the following formats to specify a color. +--------------------------------------+--------------------------------------+ @@ -74,45 +77,57 @@ "Red", "Green", and "Blue" are the intensities of those colors. In combination, they represent the colorspace. -Matplotlib draws Artists based on the ``zorder`` parameter. If there are no -specified values, Matplotlib defaults to the order of the Artists added to the -Axes. - -The alpha for an Artist controls opacity. It indicates how the RGB color of the -new Artist combines with RGB colors already on the Axes. +Transparency +============ -The two Artists combine with alpha compositing. Matplotlib uses the equation -below to compute the result of blending a new Artist. +The *alpha* value of a color specifies its transparency, where 0 is fully +transparent and 1 is fully opaque. When a color is semi-transparent, the +background color will show through. -:: +The *alpha* value determines the resulting color by blending the +foreground color with the background color according to the formula - RGB_{new} = RGB_{below} * (1 - \\alpha) + RGB_{artist} * \\alpha +.. math:: -Alpha of 1 indicates the new Artist completely covers the previous color. -Alpha of 0 for top color is not visible; however, it contributes to blending -for intermediate values as the cumulative result of all previous Artists. The -following table contains examples. + RGB_{result} = RGB_{background} * (1 - \\alpha) + RGB_{foreground} * \\alpha -+---------------+-------------------------------------------------------------+ -| Alpha value | Visual | -+===============+=============================================================+ -| ``0.3`` | .. image:: ../../_static/color_zorder_A.png | -+---------------+-------------------------------------------------------------+ -| ``1`` | .. image:: ../../_static/color_zorder_B.png | -+---------------+-------------------------------------------------------------+ - -.. note:: +The following plot illustrates the effect of transparency. +""" - Changing the order of Artists will generally change the resulting figure. +import matplotlib.pyplot as plt +from matplotlib.patches import Rectangle +import numpy as np +fig, ax = plt.subplots(figsize=(6.5, 1.65), layout='constrained') +ax.add_patch(Rectangle((-0.2, -0.35), 11.2, 0.7, color='C1', alpha=0.8)) +for i, alpha in enumerate(np.linspace(0, 1, 11)): + ax.add_patch(Rectangle((i, 0.05), 0.8, 0.6, alpha=alpha, zorder=0)) + ax.text(i+0.4, 0.85, f"{alpha:.1f}", ha='center') + ax.add_patch(Rectangle((i, -0.05), 0.8, -0.6, alpha=alpha, zorder=2)) +ax.set_xlim(-0.2, 13) +ax.set_ylim(-1, 1) +ax.set_title('alpha values') +ax.text(11.3, 0.6, 'zorder=1', va='center', color='C0') +ax.text(11.3, 0, 'zorder=2\nalpha=0.8', va='center', color='C1') +ax.text(11.3, -0.6, 'zorder=3', va='center', color='C0') +ax.axis('off') -"CN" color selection --------------------- -Matplotlib converts "CN" colors to RGBA when drawing Artists. The -:doc:`/tutorials/intermediate/color_cycle` section contains additional -information about controlling colors and style properties. -""" +############################################################################### +# +# The orange rectangle is semi-transparent with *alpha* = 0.8. The top row of +# blue squares is drawn below and the bottom row of blue squares is drawn on +# top of the orange rectangle. +# +# See also :doc:`/gallery/misc/zorder_demo` to learn more on the drawing order. +# +# +# "CN" color selection +# ==================== +# +# Matplotlib converts "CN" colors to RGBA when drawing Artists. The +# :doc:`/tutorials/intermediate/color_cycle` section contains additional +# information about controlling colors and style properties. import numpy as np @@ -144,7 +159,7 @@ def demo(sty): # .. _xkcd-colors: # # Comparison between X11/CSS4 and xkcd colors -# ------------------------------------------- +# =========================================== # # The xkcd colors come from a `user survey conducted by the webcomic xkcd # `__.