README.rst.template

``bezier``
==========

    Helper for B |eacute| zier Curves, Triangles, and Higher Order Objects

|circle-build| |travis-build| |appveyor-build| |coverage|{pypi}{versions}{docs}{zenodo}{joss}

.. |eacute| unicode:: U+000E9 .. LATIN SMALL LETTER E WITH ACUTE
   :trim:

{toctree}This library provides:

* Support for B |eacute| zier :mod:`Curves <bezier.curve>`
* Support for B |eacute| zier :mod:`Surfaces <bezier.surface>`

Dive in and take a look!

.. image:: {img_prefix}images/surfaces6Q_and_7Q.png
   :align: center

Why B |eacute| zier?
--------------------

A B |eacute| zier curve (and surface, etc.) is a parametric curve
that uses the `Bernstein basis`_:

{bernstein_basis}

to define a curve as a linear combination:

{bezier_defn}

This comes from the fact that the weights sum to one:

{sum_to_unity}

This can be generalized to higher order by considering three, four, etc.
non-negative weights that sum to one (in the above we have the two
non-negative weights :math:`s` and :math:`1 - s`).

Due to their simple form, B |eacute| zier curves:

* can easily model geometric objects as parametric curves, surfaces, etc.
* can be computed in an efficient and numerically stable way via
  `de Casteljau's algorithm`_
* can utilize convex optimization techniques for many algorithms (such as
  curve-curve intersection), since curves (and surfaces, etc.)
  are convex combinations of the basis

Many applications -- as well as the history of their development --
are described in
"The Bernstein polynomial basis: A centennial `retrospective`_",
for example;

* aids physical analysis using finite element methods (`FEM`_) on
  isogeometric models by using geometric shape functions called
  `NURBS`_ to represent data
* used in robust control of dynamic systems; utilizes convexity to
  create a hull of curves

.. _retrospective: https://dx.doi.org/10.1016/j.cagd.2012.03.001
.. _Bernstein basis: https://en.wikipedia.org/wiki/Bernstein_polynomial
.. _de Casteljau's algorithm: https://en.wikipedia.org/wiki/De_Casteljau%27s_algorithm
.. _FEM: https://en.wikipedia.org/wiki/Finite_element_method
.. _NURBS: https://en.wikipedia.org/wiki/Non-uniform_rational_B-spline

Installing
----------

The ``bezier`` Python package can be installed with `pip`_:

.. code-block:: console

   $ python    -m pip install --upgrade bezier
   $ python3.7 -m pip install --upgrade bezier

To install a pure Python version (i.e. with no binary extensions):

.. code-block:: console

   $ BEZIER_NO_EXTENSIONS=true \
   >   python  -m pip install --upgrade bezier --no-binary=bezier

``bezier`` is open-source, so you can alternatively grab the source
code from `GitHub`_ and install from source.

.. _pip: https://pip.pypa.io
.. _GitHub: https://github.com/dhermes/bezier/

Getting Started
---------------

For example, to create a curve:

{code_block1}

   >>> nodes1 = np.asfortranarray([
   ...     [0.0, 0.5, 1.0],
   ...     [0.0, 1.0, 0.0],
   ... ])
   >>> curve1 = bezier.Curve(nodes1, degree=2)

The intersection (points) between two curves can
also be determined:

{code_block2}

   >>> nodes2 = np.asfortranarray([
   ...     [0.0, 0.25,  0.5, 0.75, 1.0],
   ...     [0.0, 2.0 , -2.0, 2.0 , 0.0],
   ... ])
   >>> curve2 = bezier.Curve.from_nodes(nodes2)
   >>> intersections = curve1.intersect(curve2)
   >>> intersections
   array([[0.31101776, 0.68898224, 0. , 1. ],
          [0.31101776, 0.68898224, 0. , 1. ]])
   >>> s_vals = np.asfortranarray(intersections[0, :])
   >>> points = curve1.evaluate_multi(s_vals)
   >>> points
   array([[0.31101776, 0.68898224, 0. , 1. ],
          [0.42857143, 0.42857143, 0. , 0. ]])

and then we can plot these curves (along with their
intersections):

{code_block3}

   >>> import matplotlib.pyplot as plt
   >>> import seaborn
   >>> seaborn.set()
   >>>
   >>> ax = curve1.plot(num_pts=256)
   >>> _ = curve2.plot(num_pts=256, ax=ax)
   >>> lines = ax.plot(
   ...     points[0, :], points[1, :],
   ...     marker="o", linestyle="None", color="black")
   >>> _ = ax.axis("scaled")
   >>> _ = ax.set_xlim(-0.125, 1.125)
   >>> _ = ax.set_ylim(-0.0625, 0.625)
   >>> plt.show()

{testcleanup}.. image:: {img_prefix}images/curves1_and_13.png
   :align: center

For API-level documentation, check out the B |eacute| zier Python
:doc:`package <python/reference/bezier>` documentation.

Development
-----------

To work on adding a feature or to run the functional tests, see the
:doc:`DEVELOPMENT doc <development>` for more information on how to get
started.

Citation
--------

For publications that use ``bezier``, there is a `JOSS paper`_ that can be
cited. The following BibTeX entry can be used:

.. code-block:: rest

   @article{{Hermes2017,
     doi = {{10.21105/joss.00267}},
     url = {{https://doi.org/10.21105%2Fjoss.00267}},
     year = {{2017}},
     month = {{Aug}},
     publisher = {{The Open Journal}},
     volume = {{2}},
     number = {{16}},
     pages = {{267}},
     author = {{Danny Hermes}},
     title = {{Helper for B{{\'{{e}}}}zier Curves, Triangles, and Higher Order Objects}},
     journal = {{The Journal of Open Source Software}}
   }}

A **particular** version of this library can be cited via a Zenodo DOI; see
a full `list by version`_.

.. _JOSS paper: https://joss.theoj.org/papers/10.21105/joss.00267
.. _list by version: https://zenodo.org/search?page=1&size=20&q=conceptrecid:%22838307%22&sort=-version&all_versions=True

License
-------

``bezier`` is made available under the Apache 2.0 License. For more
details, see `the LICENSE`_.

{extra_links}.. _the LICENSE: https://github.com/dhermes/bezier/blob/{revision}/LICENSE

{docs_img}.. |circle-build| image:: {circleci_badge}
   :target: https://circleci.com/gh/dhermes/bezier{circleci_path}
   :alt: CircleCI Build
.. |travis-build| image:: {travis_badge}
   :target: https://travis-ci.org/dhermes/bezier{travis_path}
   :alt: Travis Build
.. |appveyor-build| image:: {appveyor_badge}
   :target: https://ci.appveyor.com/project/dhermes/bezier{appveyor_path}
   :alt: AppVeyor CI Build{pypi_img}{versions_img}
.. |coverage| image:: {coveralls_badge}
   :target: https://coveralls.io/{coveralls_path}
   :alt: Code Coverage{zenodo_img}{joss_img}