README.rst.template

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

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

|linux-build| |macos-build| |windows-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:`Triangles <bezier.triangle>`

Dive in and take a look!

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

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

A B |eacute| zier curve (and triangle, 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, triangles, 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 triangles, 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.11 -m pip install --upgrade bezier
   $ # To install optional dependencies, e.g. SymPy
   $ python     -m pip install --upgrade bezier[full]

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

.. code-block:: console

   $ BEZIER_NO_EXTENSION=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}

   >>> import bezier
   >>> import numpy as np
   >>> 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 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)

{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

{citation}

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}.. |linux-build| image:: {linux_badge}
   :target: https://github.com/dhermes/bezier/actions{linux_path}
   :alt: Linux Build (GitHub Actions)
.. |macos-build| image:: {macos_badge}
   :target: https://github.com/dhermes/bezier/actions{macos_path}
   :alt: macOS Build (GitHub Actions)
.. |windows-build| image:: {windows_badge}
   :target: https://github.com/dhermes/bezier/actions{windows_path}
   :alt: Windows Build (GitHub Actions){pypi_img}{versions_img}
.. |coverage| image:: {coveralls_badge}
   :target: https://coveralls.io/{coveralls_path}
   :alt: Code Coverage{zenodo_img}{joss_img}