8000 Improve docstring of Arc by timhoffm · Pull Request #12737 · matplotlib/matplotlib · GitHub
[go: up one dir, main page]
Skip to content

Improve docstring of Arc #12737

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

Merged
merged 1 commit into from
Nov 5, 2018
Merged

Improve docstring of Arc #12737

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
10000
Diff view
100 changes: 54 additions & 46 deletions lib/matplotlib/patches.py
View file
Open in desktop
< 10000 /tr>
Original file line number Diff line number Diff line change
Expand Up @@ -1559,14 +1559,15 @@ def get_radius(self):

class Arc(Ellipse):
"""
An elliptical arc. Because it performs various optimizations, it
can not be filled.

The arc must be used in an :class:`~matplotlib.axes.Axes`
instance---it can not be added directly to a
:class:`~matplotlib.figure.Figure`---because it is optimized to
only render the segments that are inside the axes bounding box
with high resolution.
An elliptical arc, i.e. a segment of an ellipse.

Due to internal optimizations, there are certain restrictions on using Arc:

- The arc cannot be filled.

- The arc must be used in an :class:`~.axes.Axes` instance---it can not be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If you add spaces around ---, would it turn into a real em-dash?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No.

grafik

added directly to a `.Figure`---because it is optimized to only render
the segments that are inside the axes bounding box with high resolution.
"""
def __str__(self):
pars = (self.center[0], self.center[1], self.width,
Expand All @@ -1579,32 +1580,35 @@ def __str__(self):
def __init__(self, xy, width, height, angle=0.0,
theta1=0.0, theta2=360.0, **kwargs):
"""
The following args are supported:

*xy*
center of ellipse

*width*
length of horizontal axis

*height*
length of vertical axis
Parameters
----------
xy : (float, float)
The center of the ellipse.

*angle*
rotation in degrees (anti-clockwise)
width : float
The length of the horizontal axis.

*theta1*
starting angle of the arc in degrees
height : float
The length of the vertical axis.

*theta2*
ending angle of the arc in degrees
angle : float
Rotation of the ellipse in degrees (anti-clockwise).

If *theta1* and *theta2* are not provided, the arc will form a
complete ellipse.
theta1, theta2 : float, optional
Starting and ending angles of the arc in degrees. These values
are relative to *angle*, .e.g. if *angle* = 45 and *theta1* = 90
the absolute starting angle is 135.
Default *theta1* = 0, *theta2* = 360, i.e. a complete ellipse.

Valid kwargs are:
Other Parameters
----------------
**kwargs : `.Patch` properties
Most `.Patch` properties are supported as keyword arguments,
with the exception of *fill* and *facecolor* because filling is
not supported.

%(Patch)s

"""
fill = kwargs.setdefault('fill', False)
if fill:
Expand All @@ -1618,12 +1622,16 @@ def __init__(self, xy, width, height, angle=0.0,
@artist.allow_rasterization
def draw(self, renderer):
"""
Draw the arc to the given *renderer*.

Notes
-----
Ellipses are normally drawn using an approximation that uses
eight cubic Bezier splines. The error of this approximation
is 1.89818e-6, according to this unverified source:

Lancaster, Don. Approximating a Circle or an Ellipse Using
Four Bezier Cubic Splines.
Lancaster, Don. *Approximating a Circle or an Ellipse Using
Four Bezier Cubic Splines.*

http://www.tinaja.com/glib/ellipse4.pdf

Expand All @@ -1639,27 +1647,27 @@ def draw(self, renderer):
with each visible arc using a fixed number of spline segments
(8). The algorithm proceeds as follows:

1. The points where the ellipse intersects the axes bounding
box are located. (This is done be performing an inverse
transformation on the axes bbox such that it is relative
to the unit circle -- this makes the intersection
calculation much easier than doing rotated ellipse
intersection directly).
1. The points where the ellipse intersects the axes bounding
box are located. (This is done be performing an inverse
transformation on the axes bbox such that it is relative
to the unit circle -- this makes the intersection
calculation much easier than doing rotated ellipse
intersection directly).

This uses the "line intersecting a circle" algorithm
from:
This uses the "line intersecting a circle" algorithm
from:

Vince, John. Geometry for Computer Graphics: Formulae,
Examples & Proofs. London: Springer-Verlag, 2005.
Vince, John. *Geometry for Computer Graphics: Formulae,
Examples & Proofs.* London: Springer-Verlag, 2005.

2. The angles of each of the intersection points are
calculated.
2. The angles of each of the intersection points are
calculated.

3. Proceeding counterclockwise starting in the positive
x-direction, each of the visible arc-segments between the
pairs of vertices are drawn using the Bezier arc
approximation technique implemented in
:meth:`matplotlib.path.Path.arc`.
3. Proceeding counterclockwise starting in the positive
x-direction, each of the visible arc-segments between the
pairs of vertices are drawn using the Bezier arc
approximation technique implemented in
:meth:`matplotlib.path.Path.arc`.
"""
if not hasattr(self, 'axes'):
raise RuntimeError('Arcs can only be used in Axes instances')
Expand Down
0