Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/matplotlib/_enums.py: 37%

1""" 

2Enums representing sets of strings that Matplotlib uses as input parameters. 

3 

4Matplotlib often uses simple data types like strings or tuples to define a 

5concept; e.g. the line capstyle can be specified as one of 'butt', 'round', 

6or 'projecting'. The classes in this module are used internally and serve to 

7document these concepts formally. 

8 

9As an end-user you will not use these classes directly, but only the values 

10they define. 

11""" 

12 

13from enum import Enum, auto 

14from matplotlib import _docstring 

15 

16 

17class _AutoStringNameEnum(Enum): 

18 """Automate the ``name = 'name'`` part of making a (str, Enum).""" 

19 

20 def _generate_next_value_(name, start, count, last_values): 

21 return name 

22 

23 def __hash__(self): 

24 return str(self).__hash__() 

25 

26 

27class JoinStyle(str, _AutoStringNameEnum): 

28 """ 

29 Define how the connection between two line segments is drawn. 

30 

31 For a visual impression of each *JoinStyle*, `view these docs online 

32 <JoinStyle>`, or run `JoinStyle.demo`. 

33 

34 Lines in Matplotlib are typically defined by a 1D `~.path.Path` and a 

35 finite ``linewidth``, where the underlying 1D `~.path.Path` represents the 

36 center of the stroked line. 

37 

38 By default, `~.backend_bases.GraphicsContextBase` defines the boundaries of 

39 a stroked line to simply be every point within some radius, 

40 ``linewidth/2``, away from any point of the center line. However, this 

41 results in corners appearing "rounded", which may not be the desired 

42 behavior if you are drawing, for example, a polygon or pointed star. 

43 

44 **Supported values:** 

45 

46 .. rst-class:: value-list 

47 

48 'miter' 

49 the "arrow-tip" style. Each boundary of the filled-in area will 

50 extend in a straight line parallel to the tangent vector of the 

51 centerline at the point it meets the corner, until they meet in a 

52 sharp point. 

53 'round' 

54 stokes every point within a radius of ``linewidth/2`` of the center 

55 lines. 

56 'bevel' 

57 the "squared-off" style. It can be thought of as a rounded corner 

58 where the "circular" part of the corner has been cut off. 

59 

60 .. note:: 

61 

62 Very long miter tips are cut off (to form a *bevel*) after a 

63 backend-dependent limit called the "miter limit", which specifies the 

64 maximum allowed ratio of miter length to line width. For example, the 

65 PDF backend uses the default value of 10 specified by the PDF standard, 

66 while the SVG backend does not even specify the miter limit, resulting 

67 in a default value of 4 per the SVG specification. Matplotlib does not 

68 currently allow the user to adjust this parameter. 

69 

70 A more detailed description of the effect of a miter limit can be found 

71 in the `Mozilla Developer Docs 

72 <https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-miterlimit>`_ 

73 

74 .. plot:: 

75 :alt: Demo of possible JoinStyle's 

76 

77 from matplotlib._enums import JoinStyle 

78 JoinStyle.demo() 

79 

80 """ 

81 

82 miter = auto() 

83 round = auto() 

84 bevel = auto() 

85 

86 @staticmethod 

87 def demo(): 

88 """Demonstrate how each JoinStyle looks for various join angles.""" 

89 import numpy as np 

90 import matplotlib.pyplot as plt 

91 

92 def plot_angle(ax, x, y, angle, style): 

93 phi = np.radians(angle) 

94 xx = [x + .5, x, x + .5*np.cos(phi)] 

95 yy = [y, y, y + .5*np.sin(phi)] 

96 ax.plot(xx, yy, lw=12, color='tab:blue', solid_joinstyle=style) 

97 ax.plot(xx, yy, lw=1, color='black') 

98 ax.plot(xx[1], yy[1], 'o', color='tab:red', markersize=3) 

99 

100 fig, ax = plt.subplots(figsize=(5, 4), constrained_layout=True) 

101 ax.set_title('Join style') 

102 for x, style in enumerate(['miter', 'round', 'bevel']): 

103 ax.text(x, 5, style) 

104 for y, angle in enumerate([20, 45, 60, 90, 120]): 

105 plot_angle(ax, x, y, angle, style) 

106 if x == 0: 

107 ax.text(-1.3, y, f'{angle} degrees') 

108 ax.set_xlim(-1.5, 2.75) 

109 ax.set_ylim(-.5, 5.5) 

110 ax.set_axis_off() 

111 fig.show() 

112 

113 

114JoinStyle.input_description = "{" \ 

115 + ", ".join([f"'{js.name}'" for js in JoinStyle]) \ 

116 + "}" 

117 

118 

119class CapStyle(str, _AutoStringNameEnum): 

120 r""" 

121 Define how the two endpoints (caps) of an unclosed line are drawn. 

122 

123 How to draw the start and end points of lines that represent a closed curve 

124 (i.e. that end in a `~.path.Path.CLOSEPOLY`) is controlled by the line's 

125 `JoinStyle`. For all other lines, how the start and end points are drawn is 

126 controlled by the *CapStyle*. 

127 

128 For a visual impression of each *CapStyle*, `view these docs online 

129 <CapStyle>` or run `CapStyle.demo`. 

130 

131 By default, `~.backend_bases.GraphicsContextBase` draws a stroked line as 

132 squared off at its endpoints. 

133 

134 **Supported values:** 

135 

136 .. rst-class:: value-list 

137 

138 'butt' 

139 the line is squared off at its endpoint. 

140 'projecting' 

141 the line is squared off as in *butt*, but the filled in area 

142 extends beyond the endpoint a distance of ``linewidth/2``. 

143 'round' 

144 like *butt*, but a semicircular cap is added to the end of the 

145 line, of radius ``linewidth/2``. 

146 

147 .. plot:: 

148 :alt: Demo of possible CapStyle's 

149 

150 from matplotlib._enums import CapStyle 

151 CapStyle.demo() 

152 

153 """ 

154 butt = auto() 

155 projecting = auto() 

156 round = auto() 

157 

158 @staticmethod 

159 def demo(): 

160 """Demonstrate how each CapStyle looks for a thick line segment.""" 

161 import matplotlib.pyplot as plt 

162 

163 fig = plt.figure(figsize=(4, 1.2)) 

164 ax = fig.add_axes([0, 0, 1, 0.8]) 

165 ax.set_title('Cap style') 

166 

167 for x, style in enumerate(['butt', 'round', 'projecting']): 

168 ax.text(x+0.25, 0.85, style, ha='center') 

169 xx = [x, x+0.5] 

170 yy = [0, 0] 

171 ax.plot(xx, yy, lw=12, color='tab:blue', solid_capstyle=style) 

172 ax.plot(xx, yy, lw=1, color='black') 

173 ax.plot(xx, yy, 'o', color='tab:red', markersize=3) 

174 

175 ax.set_ylim(-.5, 1.5) 

176 ax.set_axis_off() 

177 fig.show() 

178 

179 

180CapStyle.input_description = "{" \ 

181 + ", ".join([f"'{cs.name}'" for cs in CapStyle]) \ 

182 + "}" 

183 

184_docstring.interpd.update({'JoinStyle': JoinStyle.input_description, 

185 'CapStyle': CapStyle.input_description})