Skip to content

[Doc]: Clarify default capstyle #21979

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
StefRe opened this issue Dec 16, 2021 · 6 comments · Fixed by #22053
Closed

[Doc]: Clarify default capstyle #21979

StefRe opened this issue Dec 16, 2021 · 6 comments · Fixed by #22053
Labels
Documentation
Milestone
v3.5.2

Comments

@StefRe
Copy link
Contributor

StefRe commented Dec 16, 2021

Documentation Link

https://matplotlib.org/devdocs/api/_enums_api.html#matplotlib._enums.CapStyle

Problem

The demo states that the default capstyle is projecting, which is true for Line2D but not for PathPatch (where the default is 'butt').

import matplotlib.pyplot as plt
import matplotlib as mpl

fig,ax = plt.subplots(figsize=(2,1), layout='constrained')

xx = [0, 1]
yy = [0, 0]
ax.plot(xx, yy, lw=12, color='tab:blue')
ax.plot(xx, yy, lw=1, color='black')
ax.plot(xx, yy, 'o', color='tab:red', markersize=3)
ax.add_patch(mpl.patches.PathPatch(mpl.path.Path([[0, 0],[1, 0]]), lw=20, color='C1'))
ax.set_axis_off()

Figure_6

(see also https://stackoverflow.com/a/70381813/3944322)

Suggested improvement

Change (default) to (default for Line2D) in

matplotlib/lib/matplotlib/_enums.py

Line 171 in 98115e9

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

Matplotlib Version

3.5.0
@timhoffm
Copy link
Member

If we mention the Line2D default, we should also mention the PathPatch default.

I'm undecided whether that's still reasonable in the plot or whether we should discuss defaults in a dedicated section. I tend to go with the latter.

Joinstyle is also different (#18597). While at it, it should be addressed in the same fashion.

@StefRe
Copy link
Contributor Author

StefRe commented Dec 16, 2021

whether we should discuss defaults in a dedicated section

maybe just document the default capstyle in set_capstyle:

matplotlib/lib/matplotlib/patches.py

Lines 473 to 475 in be35409

def set_capstyle(self, s):
"""
Set the `.CapStyle`.

matplotlib/lib/matplotlib/collections.py

Lines 632 to 634 in 092f833

def set_capstyle(self, cs):
"""
Set the `.CapStyle` for the collection (for all its elements).

matplotlib/lib/matplotlib/lines.py

Lines 1343 to 1346 in 092f833

def set_solid_capstyle(self, s):
"""
How to draw the end caps if the line is solid (not `~Line2D.is_dashed`)

matplotlib/lib/matplotlib/lines.py

Lines 1329 to 1331 in 092f833

def set_dash_capstyle(self, s):
"""
How to draw the end caps if the line is `~Line2D.is_dashed`.

In addition to that we could determine the default capstyle programmatically in the demo, so that it's always up-to-date, even if one forgets about the demo when changing the default sometime in the future:

import matplotlib as mpl

fig = mpl.pyplot.figure(figsize=(4, 1.2))
ax = fig.add_axes([0.1, 0, 0.8, 0.8])
ax.set_axis_off()
ax.set(title='Cap style', ylim=(-.5, 1.5))

default_l2d = mpl.lines.Line2D([], []).get_solid_capstyle()
default_pp = mpl.patches.PathPatch(mpl.path.Path([[0, 0], [0, 0]])).get_capstyle().name

for x, style in enumerate(['butt', 'round', 'projecting']):
    if style == default_l2d == default_pp:
        default = '(default)'
    elif style == default_l2d:
        default = '(default for Line2D)'
    elif style == default_pp:
        default = '(default for PathPatch)'
    else:
        default = ''
    ax.text(x+0.25, 0.85, f'{style}\n{default}'.strip(), ha='center', va='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)

Figure_1

(the same for joinstyle)

@StefRe
Copy link
Contributor Author

StefRe commented Dec 16, 2021 •
edited
Loading

While making the example I noticed the following inconsistency:

matplotlib/lib/matplotlib/patches.py

Lines 485 to 487 in be35409

def get_capstyle(self):
"""Return the capstyle."""
return self._capstyle
and

matplotlib/lib/matplotlib/markers.py

Lines 327 to 328 in f6e0ee4

def get_capstyle(self):
return self._capstyle

return a CapStyle object while the other 3 methods return a string (i.e. ...capstyle.name).

Is this something a separate issue should be opened for? (at least it should be documented which type is returned in each case).

@StefRe
Copy link
Contributor Author

StefRe commented Dec 17, 2021

There's another exception (which is, however, correctly documented #13647):

matplotlib/lib/matplotlib/patches.py

Lines 4277 to 4282 in 1535cdc

In contrast to other patches, the default ``capstyle`` and
``joinstyle`` for `FancyArrowPatch` are set to ``"round"``.
"""
# Traditionally, the cap- and joinstyle for FancyArrowPatch are round
kwargs.setdefault("joinstyle", JoinStyle.round)
kwargs.setdefault("capstyle", CapStyle.round)

@StefRe
Copy link
Contributor Author

StefRe commented Dec 17, 2021

And the last one:

matplotlib/lib/matplotlib/markers.py

Line 288 in f6e0ee4

self._capstyle = self._user_capstyle or CapStyle.butt

Also not documented:

matplotlib/lib/matplotlib/markers.py

Lines 249 to 250 in f6e0ee4

capstyle : CapStyle, default: None
Cap style that will override the default cap style of the marker.

@StefRe
Copy link
Contributor Author

StefRe commented Dec 17, 2021

In total we seem to have the following defaults (hope that I didn't overlook anything) :

  • 'projecting' for Line2D
  • 'round' for FancyArrowPatch
  • 'butt' for all other

So maybe it's indeed not so good an idea to give the defaults in the demo but rather document them with their classes.

This was referenced Dec 27, 2021
Merged
Merged
@QuLogic QuLogic added this to the v3.5.2 milestone Jan 12, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.5.2
Development

Successfully merging a pull request may close this issue.

DOC: Document default cap styles StefRe/matplotlib
3 participants
@QuLogic @timhoffm @StefRe