matplotlib.github.com/3.4.2/_modules/matplotlib/_enums.html at main · matplotlib/matplotlib.github.com

History

333 lines (265 loc) · 31.5 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>matplotlib._enums — Matplotlib 3.4.2 documentation</title>

title="Search within Matplotlib 3.4.2 documentation"

href="../../_static/opensearch.xml"/>

</head><body>

<div id="unreleased-message"> You are reading an old version of the documentation (v3.4.2). For the latest version see <a href="/stable/">https://matplotlib.org/stable/</a> </div>

<!--

</div>

-->

<div style="float: left; position: absolute; width: 496px; bottom: 0; padding-bottom: 24px">Version 3.4.2</div>

<div id="forkongithub"><a href="https://github.com/matplotlib/matplotlib">Fork me on GitHub</a></div>

</div>

<ul>

<li><a href="../../users/installing.html">Installation</a></li>

<li><a href="../../contents.html">Documentation</a></li>

<li><a href="../../gallery/index.html">Examples</a></li>

<li><a href="../../tutorials/index.html">Tutorials</a></li>

<li><a href="../../devel/index.html">Contributing</a></li>

</form>

</li>

</ul>

</nav>

<h3>Navigation</h3>

<ul>

<a href="../../genindex.html" title="General Index"

accesskey="I">index</a></li>

<a href="../../py-modindex.html" title="Python Module Index"

>modules</a> |</li>

<li><a href="../../contents.html">contents</a> »</li>

<li class="nav-item nav-item-1"><a href="../index.html" >Module code</a> »</li>

<li class="nav-item nav-item-2"><a href="../matplotlib.html" accesskey="U">matplotlib</a> »</li>

<li class="nav-item nav-item-this"><a href="">matplotlib._enums</a></li>

</ul>

</div>

</div>

<h1>Source code for matplotlib._enums</h1><div class="highlight"><pre>

"""

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

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

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

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

document these concepts formally.

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

they define.

"""

from enum import Enum, auto

from matplotlib import cbook, docstring

class _AutoStringNameEnum(Enum):

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

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

return name

def __hash__(self):

return str(self).__hash__()

def _deprecate_case_insensitive_join_cap(s):

s_low = s.lower()

if s != s_low:

if s_low in ['miter', 'round', 'bevel']:

cbook.warn_deprecated(

"3.3", message="Case-insensitive capstyles are deprecated "

"since %(since)s and support for them will be removed "

"%(removal)s; please pass them in lowercase.")

elif s_low in ['butt', 'round', 'projecting']:

cbook.warn_deprecated(

"3.3", message="Case-insensitive joinstyles are deprecated "

"since %(since)s and support for them will be removed "

"%(removal)s; please pass them in lowercase.")

# Else, error out at the check_in_list stage.

return s_low

<div class="viewcode-block" id="JoinStyle"><a class="viewcode-back" href="../../api/_enums_api.html#matplotlib._enums.JoinStyle">[docs]</a>class JoinStyle(str, _AutoStringNameEnum):

"""

Define how the connection between two line segments is drawn.

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

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

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

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

center of the stroked line.

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

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

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

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

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

**Supported values:**

.. rst-class:: value-list

'miter'

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

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

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

sharp point.

'round'

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

lines.

'bevel'

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

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

.. note::

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

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

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

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

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

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

currently allow the user to adjust this parameter.

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

in the `Mozilla Developer Docs

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

.. plot::

:alt: Demo of possible JoinStyle's

from matplotlib._enums import JoinStyle

JoinStyle.demo()

"""

miter = auto()

round = auto()

bevel = auto()

def __init__(self, s):

s = _deprecate_case_insensitive_join_cap(s)

Enum.__init__(self)

<div class="viewcode-block" id="JoinStyle.demo"><a class="viewcode-back" href="../../api/_enums_api.html#matplotlib._enums.JoinStyle.demo">[docs]</a> @staticmethod

def demo():

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

import numpy as np

import matplotlib.pyplot as plt

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

phi = np.radians(angle)

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

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

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

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

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

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

ax.set_title('Join style')

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

ax.text(x, 5, style)

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

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

if x == 0:

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

ax.set_xlim(-1.5, 2.75)

ax.set_ylim(-.5, 5.5)

ax.set_axis_off()

fig.show()</div></div>

JoinStyle.input_description = "{" \

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

+ "}"

<div class="viewcode-block" id="CapStyle"><a class="viewcode-back" href="../../api/_enums_api.html#matplotlib._enums.CapStyle">[docs]</a>class CapStyle(str, _AutoStringNameEnum):

r"""

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

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

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

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

controlled by the *CapStyle*.

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

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

**Supported values:**

.. rst-class:: value-list

'butt'

the line is squared off at its endpoint.

'projecting'

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

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

'round'

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

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

.. plot::

:alt: Demo of possible CapStyle's

from matplotlib._enums import CapStyle

CapStyle.demo()

"""

butt = 'butt'

projecting = 'projecting'

round = 'round'

def __init__(self, s):

s = _deprecate_case_insensitive_join_cap(s)

Enum.__init__(self)

<div class="viewcode-block" id="CapStyle.demo"><a class="viewcode-back" href="../../api/_enums_api.html#matplotlib._enums.CapStyle.demo">[docs]</a> @staticmethod

def demo():

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

import matplotlib.pyplot as plt

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

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

ax.set_title('Cap style')

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

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

xx = [x, x+0.5]

yy = [0, 0]

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

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

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

ax.text(2.25, 0.55, '(default)', ha='center')

ax.set_axis_off()

fig.show()</div></div>

CapStyle.input_description = "{" \

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

+ "}"

docstring.interpd.update({'JoinStyle': JoinStyle.input_description,

'CapStyle': CapStyle.input_description})

</pre></div>

</div>

</div>

Last updated on May 08, 2021.

Created using

<a href="http://sphinx-doc.org/">Sphinx</a> 3.2.1.

Doc version v3.4.2-2-gf801f04d09-dirty.

</div>

</footer>

</body>

</html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

_enums.html

Latest commit

History

_enums.html

File metadata and controls