Converting CHANGELOG.md into RST docs.

Fixes #90.

docs/index.rst

@@ -21,6 +21,7 @@
    algorithm-helpers
    native-libraries
    development
+   releases/index
 
 This library provides:
 

docs/releases/0.0.1.rst

@@ -0,0 +1,8 @@
+``0.0.1``
+=========
+
+|pypi|
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.0.1.svg
+   :target: https://pypi.org/project/bezier/0.0.1/
+   :alt: PyPI link to release 0.0.1

docs/releases/0.1.0.rst

@@ -0,0 +1,17 @@
+``0.1.0``
+=========
+
+|pypi| |docs|
+
+Primary changes since previous release
+(`0.0.1 <https://pypi.org/project/bezier/0.0.1/>`__) are related to
+curve-curve intersection. See `the intersection
+docs <http://bezier.readthedocs.io/en/0.1.0/curve-curve-intersection.html>`__
+for examples and more information.
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.1.0.svg
+   :target: https://pypi.org/project/bezier/0.1.0/
+   :alt: PyPI link to release 0.1.0
+.. |docs| image:: https://readthedocs.org/projects/bezier/badge/?version=0.1.0
+   :target: https://bezier.readthedocs.io/en/0.1.0/
+   :alt: Documentation for release 0.1.0

docs/releases/0.1.1.rst

@@ -0,0 +1,32 @@
+``0.1.1``
+=========
+
+|pypi| |docs|
+
+Changes:
+
+-  Adding ``Curve.elevate()``
+   `method <http://bezier.readthedocs.io/en/0.1.1/reference/bezier.curve.html#bezier.curve.Curve.elevate>`__
+   for degree elevation
+-  Upgrading curve-curve intersection algorithm to ignore parallel line
+   segments that don't meet (rather than throwing
+   ``NotImplementedError``)
+-  Making ``segment_intersection()``
+   `helper <http://bezier.readthedocs.io/en/0.1.1/reference/bezier.curve.html#bezier._intersection_helpers.segment_intersection>`__
+   return a ``success`` bool instead of raising ``NotImplementedError``
+   on failure
+-  Updating docs for ``newton_refine()``
+   `helper <http://bezier.readthedocs.io/en/0.1.1/reference/bezier.curve.html#bezier._intersection_helpers.newton_refine>`__
+   with two examples and making the ``parallel_different()``
+   `helper <http://bezier.readthedocs.io/en/0.1.1/reference/bezier.curve.html#bezier._intersection_helpers.parallel_different>`__
+   a publicly documented function (as a partner to
+   ``segment_intersection()``)
+-  Adding some more examples / failures to ``curve-curve-intersection``
+   `doc <http://bezier.readthedocs.io/en/0.1.1/curve-curve-intersection.html>`__
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.1.1.svg
+   :target: https://pypi.org/project/bezier/0.1.1/
+   :alt: PyPI link to release 0.1.1
+.. |docs| image:: https://readthedocs.org/projects/bezier/badge/?version=0.1.1
+   :target: https://bezier.readthedocs.io/en/0.1.1/
+   :alt: Documentation for release 0.1.1

docs/releases/0.2.0.rst

@@ -0,0 +1,49 @@
+``0.2.0``
+=========
+
+|pypi| |docs|
+
+-  **Primary feature**: ``Surface.intersect()``
+   `method <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.surface.html#bezier.surface.Surface.intersect>`__
+   added
+-  To support intersection, needed ``CurvedPolygon``
+   `type <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.curved_polygon.html#bezier.curved_polygon.CurvedPolygon>`__,
+   i.e. an object defined only by its curved sides (whereas a
+   ``Surface`` may have interior control points)
+-  Added ``Curve.specialize()``
+   `method <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.curve.html#bezier.curve.Curve.specialize>`__
+   for chopping a ``Curve`` at arbitrary parameter values (this is also
+   used in surface-surface intersection)
+-  Added images to most documented functions and methods to illustrate
+   the concept at hand. For example the ``classify_intersection()``
+   `helper <http://bezier.readthedocs.io/en/0.2.0/algorithm-helpers.html#bezier._surface_helpers.classify_intersection>`__
+   has **seven** images to enumerate all of the possible cases covered
+   in the algorithm.
+-  Added ``Surface.locate()``
+   `method <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.surface.html#bezier.surface.Surface.locate>`__,
+   made possible by the ``newton_refine()``
+   `helper <http://bezier.readthedocs.io/en/0.2.0/algorithm-helpers.html#bezier._surface_helpers.newton_refine>`__
+-  Added `Algorithm
+   Helpers <http://bezier.readthedocs.io/en/0.2.0/algorithm-helpers.html>`__
+   doc to try to explain some of the core algorithms at work (not all
+   are documented yet). Some of this content was previously documented
+   in the ``bezier.curve`` module, but was moved. Since, documentation
+   has been added for ``get_curvature``, ``newton_refine`` (for
+   surfaces), ``classify_intersection`` (to determine how two curves
+   interact while intersecting) and for some helper classes.
+-  Added ``Surface.base_x``, ``Surface.base_y`` and ``Surface.width``
+   `properties <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.surface.html#bezier.surface.Surface.width>`__
+   to allow tracking a sub-surface during the subdivision process (this
+   is an analogue to the ``Curve.start`` and ``Curve.end``
+   `properties <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.curve.html#bezier.curve.Curve.start>`__)
+-  Added ``Curve.edge_index``, ``Curve.next_edge`` and
+   ``Curve.previous_edge``
+   `properties <http://bezier.readthedocs.io/en/0.2.0/reference/bezier.curve.html#bezier.curve.Curve.edge_index>`__
+   to allow tracking when curves are actually the sides of a ``Surface``
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.2.0.svg
+   :target: https://pypi.org/project/bezier/0.2.0/
+   :alt: PyPI link to release 0.2.0
+.. |docs| image:: https://readthedocs.org/projects/bezier/badge/?version=0.2.0
+   :target: https://bezier.readthedocs.io/en/0.2.0/
+   :alt: Documentation for release 0.2.0

docs/releases/0.2.1.rst

@@ -0,0 +1,32 @@
+``0.2.1``
+=========
+
+|pypi| |docs|
+
+-  Added ``Curve.locate()`` public
+   `method <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.curve.html#bezier.curve.Curve.locate>`__
+   and ``_curve_helpers.newton_refine()``
+   `helper <http://bezier.readthedocs.io/en/0.2.1/algorithm-helpers.html#bezier._curve_helpers.newton_refine>`__
+-  Adding optional ``color`` to ``Surface.plot()``
+   `method <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.surface.html#bezier.surface.Surface.plot>`__
+-  Adding ``Surface.elevate()``
+   `method <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.surface.html#bezier.surface.Surface.elevate>`__
+   for degree elevation
+-  Fixing nodes defining the `self-intersecting
+   curve <http://bezier.readthedocs.io/en/0.2.1/curve-curve-intersection.html#detecting-self-intersections>`__
+   in ``curve-curve-intersection`` (no code in ``bezier`` was broken /
+   fixed, just "bad" docs)
+-  Allow wiggle outside of ``[0, 1]`` when intersecting linearizations
+   in ``from_linearized()``
+-  Collapsing almost-same parameter values in ``intersect_one_round()``
+   (via ``from_linearized()``). Previously checked for bitwise equality
+   and relied on checking values at the boundary of a subdivided
+   interval
+-  Adding non-public ``bezier._plot_helpers`` module
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.2.1.svg
+   :target: https://pypi.org/project/bezier/0.2.1/
+   :alt: PyPI link to release 0.2.1
+.. |docs| image:: https://readthedocs.org/projects/bezier/badge/?version=0.2.1
+   :target: https://bezier.readthedocs.io/en/0.2.1/
+   :alt: Documentation for release 0.2.1

docs/releases/0.3.0.rst

@@ -0,0 +1,103 @@
+``0.3.0``
+=========
+
+|pypi| |docs|
+
+Performance Optimizations
+-------------------------
+
+-  Adding ``__slots__`` for all classes
+-  Removing all usage of ``@property`` calls from internal callers (to
+   avoid function call overhead)
+-  Avoiding un-necessary data copying, e.g. ``nodes[[0], :]`` creates a
+   copy but ``nodes[0, :].reshape((1, 2))``
+   does not (`more
+   details <https://docs.scipy.org/doc/numpy-1.6.0/reference/arrays.indexing.html#advanced-indexing>`__)
+-  Adding ``_verify`` switches to selectively disable overly defensive
+   value checking. Added to ``CurvedPolygon``
+   `constructor <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.curved_polygon.html#bezier.curved_polygon.CurvedPolygon>`__,
+   ``Surface.evaluate_barycentric()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_barycentric>`__),
+   ``Surface.evaluate_cartesian()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_cartesian>`__),
+   ``Surface.evaluate_multi()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_multi>`__)
+   and
+   ``Surface.intersect()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.intersect>`__).
+   Internal callers with already verified data now skip verification
+   steps
+-  `Bailing out
+   early <https://github.com/dhermes/bezier/commit/db816eb5a748bb997adcc2d7d9008638e22a824c>`__
+   if surface bounding boxes are disjoint in ``Surface.intersect()``
+   `method <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.intersect>`__
+
+Breaking Changes
+----------------
+
+-  Requiring ``degree`` in ``Curve``
+   (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.curve.html#bezier.curve.Curve>`__)
+   and ``Surface``
+   (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface>`__)
+   constructors, but adding ``Curve.from_nodes()``
+   (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.curve.html#bezier.curve.Curve.from_nodes>`__)
+   and ``Surface.from_nodes()``
+   (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.from_nodes>`__)
+   factories to accept nodes only (computing the degree in the
+   constructor every time is a waste of flops, especially if the caller
+   knows the degree)
+-  `Removing <https://github.com/dhermes/bezier/commit/3393b9010c26b55a9c29afc2702426bb179b85a1>`__
+   public ``Curve.copy()``
+   (`doc <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.curve.html#bezier.curve.Curve.copy>`__)
+   and ``Surface.copy()``
+   (`doc <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.surface.html#bezier.surface.Surface.copy>`__)
+-  `Removing <https://github.com/dhermes/bezier/commit/3393b9010c26b55a9c29afc2702426bb179b85a1>`__
+   custom equality checks for ``Curve``
+   (`doc <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.curve.html#bezier.curve.Curve.__eq__>`__)
+   and ``Surface``
+   (`doc <http://bezier.readthedocs.io/en/0.2.1/reference/bezier.surface.html#bezier.surface.Surface.__eq__>`__)
+   objects. The previous implementation did not factor in all relevant
+   values
+-  Returning ``1xD`` arrays `instead of
+   flattened <https://github.com/dhermes/bezier/commit/b5e5b327594c6143956ed98703f596ff82b7501a>`__
+   ``D``-dimensional 1D arrays from
+   ``Curve.evaluate()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.curve.html#bezier.curve.Curve.evaluate>`__),
+   ``Surface.evaluate_barycentric()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_barycentric>`__),
+   ``Surface.evaluate_cartesian()`` (`doc <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_cartesian>`__),
+   and related helpers
+-  Renaming ``Intersection.left/right``
+   `properties <http://bezier.readthedocs.io/en/0.2.1/algorithm-helpers.html#bezier._intersection_helpers.Intersection.left>`__
+   as ``first/second``
+   `properties <http://bezier.readthedocs.io/en/0.3.0/algorithm-helpers.html#bezier._intersection_helpers.Intersection.first>`__
+   (They were poorly named originally, since "left" and "right" were in
+   reference to where they were used **in code**, not geometry. This
+   class is not part of the public interface, but it is documented.)
+
+Bug Fixes
+---------
+
+-  Handling cases where one corner of a surface touches another but
+   their interiors don't intersect (in the ``Surface.intersect()``
+   `method <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.intersect>`__).
+   Adding ``ignored_corner`` classification to handle these curve-curve
+   intersecions that don't contribute to a surface-surface intersection
+-  Throwing exception in the ``Curve.locate()``
+   `method <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.curve.html#bezier.curve.Curve.locate>`__
+   when the subdivided intervals are very far apart
+   (`#13 <https://github.com/dhermes/bezier/issues/13>`__)
+-  Improving ``Surface.is_valid``
+   `property <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.is_valid>`__
+   by considering the signs of the Jacobian determinant at corner nodes
+   (`#12 <https://github.com/dhermes/bezier/issues/12>`__)
+
+Miscellany
+----------
+
+-  Adding possible strategy to avoid linear convergence in ``newton_refine()``
+   `helper <http://bezier.readthedocs.io/en/0.3.0/algorithm-helpers.html#bezier._intersection_helpers.newton_refine>`__
+-  Adding AppVeyor configuration to make sure there are no Windows
+   issues, testing exclusively with ``conda`` install
+-  Updating generated images with ``matplotlib`` 2.0
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.3.0.svg
+   :target: https://pypi.org/project/bezier/0.3.0/
+   :alt: PyPI link to release 0.3.0
+.. |docs| image:: https://readthedocs.org/projects/bezier/badge/?version=0.3.0
+   :target: https://bezier.readthedocs.io/en/0.3.0/
+   :alt: Documentation for release 0.3.0

docs/releases/0.4.0.rst

@@ -0,0 +1,118 @@
+``0.4.0``
+=========
+
+|pypi| |docs|
+
+Performance Optimizations
+-------------------------
+
+-  `Adding <https://github.com/dhermes/bezier/commits/0.4.0/src/bezier/speedup.f90>`__
+   Fortran
+   `speedups <https://github.com/dhermes/bezier/blob/0.4.0/src/bezier/speedup.f90>`__
+   for many crucial computation helpers including
+
+   -  intersecting line segments
+   -  (vectorized) Horner's method for evaluating a Bézier curve at
+      multiple parameters at once
+   -  (vectorized) Horner's method for evaluating a Bézier surface
+   -  computing "linearization error" (how close a curve is to a line)
+   -  specializing a Bézier curve to a sub-interval
+   -  using Newton's method to refine a curve-curve intersection
+
+-  `Adding <https://github.com/dhermes/bezier/commit/dcf40f4c9ed2167e96fc8f4675aeedcc2d811a0b>`__
+   ``_verify`` switch to ``Surface.locate()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.surface.html#bezier.surface.Surface.locate>`__)
+   and ``Curve.intersect()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.Curve.intersect>`__)
+   to selectively disable overly defensive value checking. (Making sure
+   to use this switch during "internal" computation.)
+-  Making sure NumPy arrays are Fortan-contiguous as often as possible
+   (e.g. snippets and source, via ``np.asfortranarray()``). This is to
+   avoid (and emphasize) a non-trivial overhead when passing a
+   C-contiguous array to a Fortran function.
+   (`03a7242 <https://github.com/dhermes/bezier/commit/03a72428c6f9d3bd3a1fac9b7f9afa615ce12d46>`__,
+   `6064e4c <https://github.com/dhermes/bezier/commit/6064e4c314d8d717873d46e6ef35c0bbc9772728>`__,
+   `f1804f4 <https://github.com/dhermes/bezier/commit/f1804f442f190d0bc36782e940ee0b8a68c5ecd6>`__)
+-  Using Horner's method in ``Curve.evaluate_multi()`` and
+   ``Surface.evaluate_barycentric()``, rather than inferior (sometimes
+   non-vectorized) approaches
+   (`dee8181 <https://github.com/dhermes/bezier/commit/dee81813e34d5f69c52f48aa90f7c11eb4ddc3ec>`__,
+   `2611e64 <https://github.com/dhermes/bezier/commit/2611e64a735e46317cce08a41270d61024705fd9>`__)
+-  Made surface-surface intersection more resilient / lenient for corner
+   intersections. For "nearby" intersections, parameter values can be
+   rounded to ``0`` or ``1``.
+   (`4a8458c <https://github.com/dhermes/bezier/commit/4a8458c823d8acc185818f856889cff6f46300d3>`__)
+
+New Features
+------------
+
+-  `Adding <https://github.com/dhermes/bezier/commit/e72ca20f0f4ee0f6399b56805b30fe67a02aa04f>`__
+   optional ``strategy`` argument (one of geometric or algebraic) to the
+   ``Surface.intersect()``
+   `method <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.surface.html#bezier.surface.Surface.intersect>`__
+
+   -  Added "algebraic" ``IntersectionStrategy``
+      `enum <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.IntersectionStrategy>`__
+      via curve
+      `implicitization <https://github.com/dhermes/bezier/commits/0.4.0/src/bezier/_implicitization.py>`__
+      (`reference <https://en.wikipedia.org/wiki/Resultant>`__)
+
+-  Adding ``Curve.reduce_()``
+   `method <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.Curve.reduce_>`__
+   which acts as a partial inverse to ``Curve.elevate()``
+   `method <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.Curve.elevate>`__.
+   It is only a complete inverse when a curve is degree-elevated,
+   otherwise it returns the "best" reduced form (in the least squares
+   sense).
+
+Interface Changes
+-----------------
+
+-  (**Breaking change**)
+   `Removing <https://github.com/dhermes/bezier/commit/828f4238971b12a9d494ce38387cec855d063c91>`__
+   ``show`` keyword from ``Curve.plot()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.Curve.plot>`__),
+   ``Surface.plot()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.surface.html#bezier.surface.Surface.plot>`__)
+   and ``CurvedPolygon.plot()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curved_polygon.html#bezier.curved_polygon.CurvedPolygon.plot>`__)
+-  `Adding <https://github.com/dhermes/bezier/commit/ce838a2aaef2281f06603d1c76324a3aa8289cf9>`__
+   ``color`` keyword to ``Curve.plot()``
+   `method <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.Curve.plot>`__
+-  `Adding <https://github.com/dhermes/bezier/commit/dcbeefc25b7f5f9a1fa725dac04e81a43039f680>`__
+   ``alpha`` keyword to ``Curve.plot()``
+   `method <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.curve.html#bezier.curve.Curve.plot>`__
+-  (**Breaking change**)
+   `Splitting <https://github.com/dhermes/bezier/commit/cea88285b8c9002a57efd88e69b5bd2ef46e7ca7>`__
+   the ``Surface.evaluate_multi()``
+   `method <http://bezier.readthedocs.io/en/0.3.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_multi>`__
+   into ``Surface.evaluate_barycentric_multi()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_barycentric_multi>`__)
+   and ``Surface.evaluate_cartesian_multi()``
+   (`doc <http://bezier.readthedocs.io/en/0.4.0/reference/bezier.surface.html#bezier.surface.Surface.evaluate_cartesian_multi>`__)
+-  `Adding <https://github.com/dhermes/bezier/commit/f0fca088ac6f70c39f9f5af457c29e3c82f094b5>`__
+   ``__dict__`` helpers on ``Curve``, ``CurvedPolygon`` and ``Surface``.
+   These are ``@property``\ s intended only for REPL use, since classes
+   with ``__slots__`` no longer have a ``__dict__`` attribute.
+
+Miscellany
+----------
+
+-  Adding ``IntersectionClassification``
+   `enum <http://bezier.readthedocs.io/en/0.4.0/algorithm-helpers.html#bezier._surface_helpers.IntersectionClassification>`__
+   to docs
+   (`ref <https://github.com/dhermes/bezier/commit/828f4238971b12a9d494ce38387cec855d063c91>`__)
+-  `Moving <https://github.com/dhermes/bezier/commit/dc4d33cfcf7f9ac6e794b856dc6d76635d362922>`__
+   most plotting into a dedicated module. More importantly, importing
+   plotting helpers at **run-time** rather at **import time**. So if
+   computational code never plots, it won't eat the import cost of
+   ``matplotlib``.
+   `Removing <https://github.com/dhermes/bezier/commit/064e2c5efe7fa6498d74a33798a363e2c8e0b83e>`__
+   ``matplotlib`` as a dependency.
+
+.. |pypi| image:: https://img.shields.io/pypi/v/bezier/0.4.0.svg
+   :target: https://pypi.org/project/bezier/0.4.0/
+   :alt: PyPI link to release 0.4.0
+.. |docs| image:: https://readthedocs.org/projects/bezier/badge/?version=0.4.0
+   :target: https://bezier.readthedocs.io/en/0.4.0/
+   :alt: Documentation for release 0.4.0