cleanup docs for new bezier functions

brunobeltran · brunobeltran · commit ee0a30c1a23c · 2020-03-20T16:45:32.000-07:00
diff --git a/lib/matplotlib/bezier.py b/lib/matplotlib/bezier.py
@@ -255,67 +255,76 @@ def point_at_t(self, t):
         return tuple(self(t))
 
     def arc_area(self):
-        r"""(Signed) area swept out by ray from origin to curve.
+        r"""
+        (Signed) area swept out by ray from origin to curve.
 
         Notes
         -----
-        Exact formula used for Bezier curves.
-
-        Now for an arbitrary bezier curve B(t), the area of the arc swept
-        out by the ray from the origin to the curve, we simply need to compute
-        :math:`\frac{1}{2}\int_0^1 B(t) \cdot n(t) dt`, where :math:`n(t) =
-        u^{(1)}(t) \hat{x}_0 - u{(0)}(t) \hat{x}_1` is the normal vector
-        oriented away from the origin and :math:`u^{(i)}(t) = \frac{d}{dt}
-        B^{(i)}(t)` is the :math:`i`th component of the curve's tangent vector.
-        (This formula can be found by applying the divergence theorem to
-        :math:`F(x,y) = [x, y]/2`.
+        A simple, analytical formula is possible for arbitrary bezier curves.
+
+        Given a bezier curve B(t), in order to calculate the area of the arc
+        swept out by the ray from the origin to the curve, we simply need to
+        compute :math:`\frac{1}{2}\int_0^1 B(t) \cdot n(t) dt`, where
+        :math:`n(t) = u^{(1)}(t) \hat{x}_0 - u{(0)}(t) \hat{x}_1` is the normal
+        vector oriented away from the origin and :math:`u^{(i)}(t) =
+        \frac{d}{dt} B^{(i)}(t)` is the :math:`i`th component of the curve's
+        tangent vector.  (This formula can be found by applying the divergence
+        theorem to :math:`F(x,y) = [x, y]/2`, and calculates the *signed* area
+        for a counter-clockwise curve, by the right hand rule).
 
         The control points of the curve are just its coefficients in a
-        Bernstein expansion, so if we let :math:`P_i = [x_i, y_i]` be the
-        :math:`i`th control point, then
+        Bernstein expansion, so if we let :math:`P_i = [P^{(0)}_i, P^{(1)}_i]`
+        be the :math:`i`'th control point, then
 
         .. math::
 
-            \frac{1}{2}\int_0^1 B(t) \cdot n(t) dt \\
-                    = \frac{1}{2}\int_0^1 B^{(0)}(t) \frac{d}{dt} B^{(1)}(t)
+            \frac{1}{2}\int_0^1 B(t) \cdot n(t) dt
+                   &= \frac{1}{2}\int_0^1 B^{(0)}(t) \frac{d}{dt} B^{(1)}(t)
                                         - B^{(1)}(t) \frac{d}{dt} B^{(0)}(t)
                                         dt \\
-                    = \frac{1}{2}\int_0^1
+                   &= \frac{1}{2}\int_0^1
                         \left( \sum_{j=0}^n P_j^{(0)} b_{j,n} \right)
                         \left( n \sum_{k=0}^{n-1} (P_{k+1}^{(1)} -
                                P_{k}^{(1)}) b_{j,n} \right)
-                      - \left( \sum_{j=0}^n P_j^{(1)} b_{j,n} \right)
+                      \\
+                      &\hspace{1em}- \left( \sum_{j=0}^n P_j^{(1)} b_{j,n} \right)
                         \left( n \sum_{k=0}^{n-1} (P_{k+1}^{(0)} -
                                 P_{k}^{(0)}) b_{j,n} \right)
                       dt
 
-        Where :math:`b_{\nu,n}(t)` is the :math:`\nu`'th Bernstein polynomial
-        of degree :math:`n`, :math:`b_{\nu, n}(t) = {n \choose \nu} t^\nu {(1 -
-        t)}^{n-\nu}`.
+        Where :math:`b_{\nu, n}(t) = {n \choose \nu} t^\nu {(1 - t)}^{n-\nu}`
+        is the :math:`\nu`'th Bernstein polynomial of degree :math:`n`.
 
-        grouping :math:`t^l(1-t)^m` terms together for each :math:`l`,
+        Grouping :math:`t^l(1-t)^m` terms together for each :math:`l`,
         :math:`m`, we get that the integrand becomes
 
         .. math::
 
-            \frac{n}{2}\int_0^1 \sum_{j=0}^n \sum_{k=0}^{n-1}
-                                \frac{{n \choose j} {{n - 1} \choose k}}
-                                     {{{2n - 1} \choose {j+k}}}
-                                [P_j^{(0)} (P_{k+1}^{(1)} - P_{k}^{(1)})
-                               - P_j^{(1)} (P_{k+1}^{(0)} - P_{k}^{(0)})]
-                                b_{j+k,2n-1}(t) dt
+            &\sum_{j=0}^n \sum_{k=0}^{n-1}
+                {n \choose j} {{n - 1} \choose k}
+                [P_j^{(0)} (P_{k+1}^{(1)} - P_{k}^{(1)})
+                    - P_j^{(1)} (P_{k+1}^{(0)} - P_{k}^{(0)})]
+                t^{j + k} {(1 - t)}^{2n - 1 - j - k}
+                \\
+            &= \sum_{j=0}^n \sum_{k=0}^{n-1}
+                \frac{{n \choose j} {{n - 1} \choose k}}
+                        {{{2n - 1} \choose {j+k}}}
+                [P_j^{(0)} (P_{k+1}^{(1)} - P_{k}^{(1)})
+                    - P_j^{(1)} (P_{k+1}^{(0)} - P_{k}^{(0)})]
+                b_{j+k,2n-1}(t)
 
-        Interchanging sum and integral, we notice that :math:`\int_0^1 b_{\nu,
-        n}(t) dt = \frac{1}{n + 1}`, so we conclude that
+        Interchanging sum and integral, and using the fact that :math:`\int_0^1
+        b_{\nu, n}(t) dt = \frac{1}{n + 1}`, we conclude that the
+        original integral (:math:`\frac{1}{2}\int_0^1 B(t) \cdot n(t) dt`) can
+        simply be written as
 
         .. math::
 
-            \frac{1}{2}\int_0^1 B(t) \cdot n(t) dt
-              = \frac{1}{4}\sum_{j=0}^n \sum_{k=0}^{n-1}
-                \frac{{n \choose j} {{n - 1} \choose k}}
-                     {{{2n - 1} \choose {j+k}}}
-                [P_j^{(0)} (P_{k+1}^{(1)} - P_{k}^{(1)})
-               - P_j^{(1)} (P_{k+1}^{(0)} - P_{k}^{(0)})]
+            \frac{1}{4}\sum_{j=0}^n \sum_{k=0}^{n-1}
+              \frac{{n \choose j} {{n - 1} \choose k}}
+                    {{{2n - 1} \choose {j+k}}}
+              [P_j^{(0)} (P_{k+1}^{(1)} - P_{k}^{(1)})
+             - P_j^{(1)} (P_{k+1}^{(0)} - P_{k}^{(0)})]
         """
         n = self.degree
         area = 0
@@ -329,6 +338,7 @@ def arc_area(self):
 
     @classmethod
     def differentiate(cls, B):
+        """Return the derivative of a BezierSegment, itself a BezierSegment"""
         dcontrol_points = B.degree*np.diff(B.control_points, axis=0)
         return cls(dcontrol_points)
 
@@ -401,6 +411,7 @@ def axis_aligned_extrema(self):
         """
         n = self.degree
         Cj = self.polynomial_coefficients
+        # much faster than .differentiate(self).polynomial_coefficients
         dCj = np.atleast_2d(np.arange(1, n+1)).T * Cj[1:]
         if len(dCj) == 0:
             return np.array([]), np.array([])
