namespace CGAL {

/*!

\mainpage User Manual
\anchor Chapter_2D_Generalized_Barycentric_Coordinates
\cgalAutoToc

\authors Dmitry Anisimov, David Bommes, Kai Hormann, and Pierre Alliez

\section gbc_introduction Introduction

The package <em>2D Generalized Barycentric Coordinates</em> offers an efficient and robust implementation of two-dimensional closed-form generalized barycentric coordinates defined for simple two-dimensional polygons. If coordinates with respect to multivariate scattered points instead of a polygon are required, please refer to natural neighbour coordinates from the package \ref PkgInterpolation2 "2D and Surface Function Interpolation". 

In particular, the package includes an implementation of \ref wp_example "Wachspress", \ref mv_example "mean value", and \ref dh_example "discrete harmonic" coordinates and provides some extra functions to compute barycentric coordinates with respect to segments (\ref seg_example "segment coordinates") and triangles (\ref tri_example "triangle coordinates"). The section \ref gbc_theory gives a short introduction to the topic of barycentric coordinates. 

\section gbc_interface Interface

Each class that computes barycentric coordinates is parameterized by a traits class. This traits class specifies types and geometric primitives that are used in the computation and must be a model of the concept `BarycentricTraits_2`.

The main entry point to the component is an input iterator over the vertices of a polygon. The polygon's vertices must follow clockwise or anticlockwise ordering and can be of any type. However, internally the classes use the type `CGAL::Point_2`, that is why an appropriate traits class that converts the user's type to `CGAL::Point_2` must be provided. The same argument holds for query points.

Mean value coordinates are the most generic coordinates in this package because they allow an arbitrary simple polygon as input. Wachspress and discrete harmonic coordinates are, by definition, limited to strictly convex polygons. Segment coordinates take as input any non-degenerate segment, and triangle coordinates allow an arbitrary non-degenerate triangle.

Segment and triangle coordinates can be computed by using either a global function or creating the corresponding class. All other generalized coordinates can be computed by creating an instance of the class `CGAL::Barycentric_coordinates::Generalized_barycentric_coordinates_2` parameterized by an appropriate coordinate type that must be a model of the concept `BarycentricCoordinates_2`.

Any point in the plane may be taken as a query point. However, we do not recommend to use Wachspress and discrete harmonic coordinates with query points outside the closure of a polygon because at some of those points these coordinates are not well-defined, as explained in the Section \ref gbc_degeneracies. 

Once instantiated for some polygon, the coordinates can be computed multiple times for different query points with respect to all the vertices of the provided polygon. Use the \ref PkgBarycentricCoordinates2Ref "Reference Manual" for the detailed interface.

The output of the computation is a set of coordinate values at the current query point with respect to all the vertices of the polygon. This output can be stored in an arbitrary container providing an appropriate output iterator. In addition, all the classes return a pointer to the last stored element and a status of the computation (Boolean true or false).

\section gbc_examples Examples

\subsection seg_example Segment Coordinates
This is a simple example to show the use of the global function \ref seg_coord_global "CGAL::Barycentric_coordinates::compute_segment_coordinates_2()". We compute coordinates at three green points along the segment \f$[v_0, v_1]\f$ and at two blue points outside this segment but along its supporting line. We use the exact kernel and return coordinates as an array of two values. Again, the symmetry of the query points helps us to recognize errors that may have occured during the computation.

\anchor seg_coord_example
\cgalFigureBegin{seg__example,segment_coordinates_example.png}
Example's point pattern.
\cgalFigureEnd

\cgalExample{Barycentric_coordinates_2/Segment_coordinates_example.cpp}

\subsection tri_example Triangle Coordinates
In this example we show how to use the class `CGAL::Barycentric_coordinates::Triangle_coordinates_2` with the `Simple_cartesian` kernel for double type. We compute coordinates for three sets of points: interior (green), boundary (red), and exterior (blue). Note that some of the coordinate values for the exterior points are negative. We use a standard container of the type <a href="https://en.cppreference.com/w/cpp/container/vector">`std::vector`</a> and <a href="https://en.cppreference.com/w/cpp/iterator/insert_iterator">`std::insert_iterator`</a> to access and store the resulting coordinate values.

\anchor tri_coord_example
\cgalFigureBegin{tri__example,triangle_coordinates_example.png}
Example's point pattern.
\cgalFigureEnd

\cgalExample{Barycentric_coordinates_2/Triangle_coordinates_example.cpp}

\subsection wp_example Wachspress Coordinates
In the following example we create 1000 random points, then we take the convex hull of this set of points as our polygon, and compute Wachspress coordinates at all the defined points. We use the `Simple_cartesian` kernel with double type as a traits class and store obtained coordinate values in a container of the type <a href="https://en.cppreference.com/w/cpp/container/vector">`std::vector`</a>. The output iterator is <a href="https://en.cppreference.com/w/cpp/iterator/back_insert_iterator">`std::back_insert_iterator`</a>.

\cgalExample{Barycentric_coordinates_2/Wachspress_coordinates_example.cpp}

\subsection dh_example Discrete Harmonic Coordinates
In this example we compute discrete harmonic coordinates for a set of green (interior), red (boundary), and blue (exterior) points with respect to a unit square. We also show how to specify the location of a query point using additional function parameters. The used kernel is exact, and we use an output container of the type <a href="https://en.cppreference.com/w/cpp/container/vector">`std::vector`</a>. Since all the points are symmetric, it is easy to debug the correctness of the obtained coordinate values. The output iterator is <a href="https://en.cppreference.com/w/cpp/iterator/back_insert_iterator">`std::back_insert_iterator`</a>.

\anchor dh_coord_example
\cgalFigureBegin{dh__example,discrete_harmonic_coordinates_example.png}
Example's point pattern.
\cgalFigureEnd

\cgalExample{Barycentric_coordinates_2/Discrete_harmonic_coordinates_example.cpp}

\subsection mv_example Mean Value Coordinates
This is an example that shows how to compute mean value coordinates for a set of green points in a star-shaped polygon. We note that this type of coordinates is well-defined for such a concave polygon while Wachspress and discrete harmonic coordinates are not. However, it may give negative coordinate values for points outside <a href="https://en.wikipedia.org/wiki/Star-shaped_polygon">the polygon's kernel</a> (shown in red). We use an inexact data type, an output container of the type <a href="https://en.cppreference.com/w/cpp/container/vector">`std::vector`</a>, and an output iterator of the type <a href="https://en.cppreference.com/w/cpp/iterator/back_insert_iterator">std::back_insert_iterator</a> to compute, access, and store the resulting coordinate values. We also show how to choose different algorithms to compute generalized barycentric coordinates (one is more precise while the other is faster).

\anchor mv_coord_example
\cgalFigureBegin{mv__example,mean_value_coordinates_example.png}
Example's point pattern.
\cgalFigureEnd

\cgalExample{Barycentric_coordinates_2/Mean_value_coordinates_example.cpp}

\subsection height_inter_example Height Interpolation for Terrain Modeling

This is an advanced example that shows how to use generalized barycentric coordinates for height interpolation with applications to terrain modelling. It also shows how to use a non-default traits class with our package instead of a `Kernel` traits class. Suppose we know the boundary of three-dimensional piece of terrain that can be represented as a polygon with several three-dimensional vertices, where the third dimension gives the corresponding height. The task is to propagate the height from the known sample points on the boundary to the polygon's interior. This gives an approximate estimation of the terrain's surface in this region.

\cgalFigureBegin{terrain__example,terrain.png}
A 2D polygon with 50 vertices representing a piece of terrain with convex and concave parts. The height is not shown.
\cgalFigureEnd

In this example we project a three-dimensional polygon orthogonally onto the two-dimensional plane using the class `CGAL::Projection_traits_xy_3`, triangulate its interior using the class `CGAL::Delaunay_mesher_2`, and compute mean value coordinates for all the obtained points with respect to all the polygon's vertices. Finally, we interpolate the height data from the polygon's boundary to its interior using the computed coordinates and the global interpolation function from the package \ref PkgInterpolation2 "2D and Surface Function Interpolation".

\cgalExample{Barycentric_coordinates_2/Terrain_height_modeling.cpp}

As a result we get a smooth function inside the polygon that approximates the underlying terrain's surface.

\cgalFigureBegin{terrain__inter__example,terrain_interpolated.png}
The interpolated data. The colour bar represents the corresponding height.
\cgalFigureEnd

\section gbc_degeneracies Degeneracies and Special Cases

\anchor compute_seg_coord
\subsection gbc_deg_segment_coordinates Segment Coordinates
Segment coordinates can be computed exactly if an exact data type is chosen. The segment itself, with respect to which we compute coordinates, must be non-degenerate. If both conditions are satisfied, then the computation never fails. However, to compute coordinates, the user must be sure about the query point being exactly on the line \f$L\f$ supporting the segment. Since in many applications this is not the case, and a query point may lie very close but not exactly on this line, the class is also able to handle this situation.

\cgalFigureBegin{projection,projection.png}
The orthogonal projection \f$p'\f$ of the vector \f$p\f$ (green) onto the vector \f$q\f$ (red).
\cgalFigureEnd

Suppose that some query point \f$v\f$ does not lie exactly on the line \f$L\f$, but is some distance \f$d\f$ away as shown in the figure above. If we want to compute the segment barycentric coordinate \f$b_1(v)\f$ with respect to the vertex \f$v_1\f$, we first find the orthogonal projection \f$p'\f$ of the vector \f$p\f$ onto the vector \f$q\f$ and then normalize it by the length of \f$q\f$. This gives the segment barycentric coordinate \f$b_1(v') = b_1(v)\f$ if \f$v\f$ lies exactly on the line.

\b Warning: do not abuse the feature described above because it does not give correct segment barycentric coordinates for the point \f$v\f$ but rather those for \f$v'\f$. Moreover, segment barycentric coordinates for a point \f$v\f$, which does not lie exactly on the line \f$L\f$, do not exist. But if the non-zero distance \f$d\f$ is due to some numerical instability when computing the location of the point \f$v\f$ or any other problem, which causes the point to be not exactly on the line, the final segment coordinates will be, at least approximately, correct.

With inexact data types, the resulting coordinate values are correct up to the precision of the chosen type.

\subsection gbc_deg_triangular_coordinates Triangle Coordinates

These coordinates can be computed exactly if an exact data type is chosen, for any query point in the plane and with respect to any non-degenerate triangle. No special cases are handled. The computation always gives the correct result. The notion of correctness depends on the precision of the used data type. Note that for exterior points some coordinate values will be negative.

\subsection gbc_deg_wachspress_coordinates Wachspress Coordinates
Wachspress coordinates are well-defined in the closure of any <em>strictly convex polygon</em>. Therefore, for any query point from the polygon's closure with an exact data type, these coordinates are computed exactly and no false result is expected. For inexact data types, the resulting precision of the computation is due to the involved algorithm and chosen data type. In the following paragraph we discuss two available algorithms for computing Wachspress coordinates. One of them is `CGAL::Barycentric_coordinates::PRECISE`, the other is `CGAL::Barycentric_coordinates::FAST`. 

\anchor wp_polygon
\cgalFigureBegin{wp__notations,wp_notations.png}
Notation for Wachspress coordinates.
\cgalFigureEnd

To compute Wachspress weights, we follow \cite cgal:bc:fhk-gcbcocp-06 and use the formula 

<center>\f$w_i = \frac{C_i}{A_{i-1}A_i}\f$</center> 

with \f$i = 1\dots n\f$ where \f$n\f$ is the number of the polygon's vertices. In order to compute the coordinates, we normalize these weights,

<center>\f$b_i = \frac{w_i}{W^{wp}}\qquad\f$ with \f$\qquad W^{wp} = \sum_{j=1}^n w_j.\f$</center>

This formula becomes unstable when approaching the boundary of the polygon (\f$\approx 1.0e-10\f$ and closer). To fix the problem, we modify the weights \f$w_i\f$ as

<center>\f$\bar{w}_i = C_i\prod_{j\not=i-1,i} A_j\f$.</center>

After the normalization as above, this gives us the precise algorithm to compute Wachspress coordinates but with \f$O(n^2)\f$ performance only. The fast \f$O(n)\f$ algorithm uses the standard weights \f$w_i\f$. Note that mathematically this modification does not change the coordinates.

It is known that for strictly convex polygons the denominator's zero set of the Wachspress coordinates (\f$W^{wp} = 0~\f$) is a curve, which (in many cases) lies quite far away from the polygon. Speaking precisely, it interpolates the intersection points of the continuations of the polygon's edges. Therefore, the computation of Wachspress coordinates outside the polygon is possible only at points that do not belong to this curve.

\cgalFigureBegin{zero__set,zero_set.png}
Zero set (red) of the Wachspress coordinates' denominator \f$W^{wp}\f$ for a non-regular hexagon.
\cgalFigureEnd

\b Warning: we do not recommend to use Wachspress coordinates for exterior points!

\subsection gbc_deg_discrete_harmonic_coordinates Discrete Harmonic Coordinates

Discrete harmonic coordinates have the same requirements as Wachspress coordinates. They are well-defined in the closure of any <em>strictly convex polygon</em> and, if an exact data type is chosen, they are computed exactly. But, unlike Wachspress basis functions, these coordinates are not necessarily positive. In particular, the weight \f$w_i\f$ is positive if and only if \f$\alpha+\beta < \pi\f$ (see the figure below for notation). For inexact data types, the precision of the computation is due to the involved algorithm and chosen data type. Again, we describe two algorithms to compute the coordinates: one is precise and one is fast.

\anchor dh_polygon
\cgalFigureBegin{dh__notations,dh_notations.png}
Notation for discrete harmonic coordinates.
\cgalFigureEnd

To compute discrete harmonic weights, we follow \cite cgal:bc:fhk-gcbcocp-06 and use the formula

<center>\f$w_i = \frac{r_{i+1}^2A_{i-1}-r_i^2B_i+r_{i-1}^2A_i}{A_{i-1}A_i}\f$</center> 

with \f$i = 1\dots n\f$ where \f$n\f$ is the number of the polygon's vertices. In order to compute the coordinates, we normalize these weights,

<center>\f$b_i = \frac{w_i}{W^{dh}}\qquad\f$ with \f$\qquad W^{dh} = \sum_{j=1}^n w_j.\f$</center>

This formula becomes unstable when approaching the boundary of the polygon (\f$\approx 1.0e-10\f$ and closer). To fix the problem, similarly to the previous subsection, we modify the weights \f$w_i\f$ as

<center>\f$\bar{w}_i = (r_{i+1}^2A_{i-1}-r_i^2B_i+r_{i-1}^2A_i)\prod_{j\not=i-1,i} A_j\f$.</center>

After the normalization as above, this gives the precise algorithm to compute discrete harmonic coordinates but with \f$O(n^2)\f$ performance only. The fast \f$O(n)\f$ algorithm uses the standard weights \f$w_i\f$. Again, mathematically this modification does not change the coordinates.

\b Warning: as for Wachspress coordinates, we do not recommend to use discrete harmonic coordinates for exterior points because the curve \f$W^{dh} = 0\f$ may have several components, and one of them interpolates the polygon's vertices. However, if you are sure that the query point does not belong to this curve, you can compute the coordinates as shown in \ref dh_example " this example".

\subsection gbc_deg_mean_value_coordinates Mean Value Coordinates

Unlike the previous coordinates, mean value coordinates cannot be computed exactly due to an inevitable square root operation. Although, if an exact data type is used, the default precision of the computation depends only on two \cgal functions: `CGAL::to_double()` and `CGAL::sqrt()`. On the other hand, mean value coordinates are well-defined everywhere in the plane for any simple polygon. In addition, if your traits class provides a more precise version of the square root function, the final precision of the computation with exact data types will depend only on the precision of that function.

\anchor mv_polygon
\cgalFigureBegin{mv__notations,mv_notations.png}
Notation for mean value coordinates.
\cgalFigureEnd

For these coordinates we also have two algorithms: one is precise and one is fast. The first one works everywhere in the plane, and the precision of the computation depends only on the chosen data type, including the remarks above. This algorithm is based on the following weight formula from \cite cgal:bc:f-wmvc-14

<center>\f$w_i = \sigma_i\bar{w}_i\qquad\f$ with \f$\qquad\bar{w}_i = (r_{i-1}r_{i+1}-d_{i-1}d_{i+1})^{1/2}\prod_{j\not= i-1,i}(r_jr_{j+1} + d_jd_{j+1})^{1/2}\qquad\f$ where \f$\qquad r_i = \|d_i\|.\f$</center> 

Since \f$\bar{w}_i\f$ is always positive, we have to append to it the proper sign \f$\sigma_i\f$ of the signed mean value weight, which can be found efficiently (see the figures below). Basically, this weight is always positive to the left of the red piecewise linear curve, and it is negative to the right of this curve, moving in anticlockwise direction. 

\cgalFigureBegin{mv__weight__signs,mv_weight_signs_convex.png,mv_weight_signs_concave.png}
Signs of the mean value weight \f$w_i\f$ depending on the region with respect to a convex polygon \f$P\f$ and a concave polygon \f$P'\f$.
\cgalFigureEnd

After the normalization of these weights as before

<center>\f$b_i = \frac{w_i}{W^{mv}}\qquad\f$ with \f$\qquad W^{mv} = \sum_{j=1}^n w_j\f$</center>

we obtain the precise \f$O(n^2)\f$ algorithm. The fast O(n) algorithm computes the weights \f$w_i\f$ using the pseudocode from <a href="https://www.inf.usi.ch/hormann/nsfworkshop/presentations/Hormann.pdf">here</a>. These weights

<center>\f$w_i = \frac{t_{i-1} + t_i}{r_i}\qquad\f$ with \f$\qquad t_i = \frac{\text{det}(d_i, d_{i+1})}{r_ir_{i+1} + d_id_{i+1}}\f$</center>

are also normalized. Note that they are unstable if a query point is closer than \f$\approx 1.0e-10\f$ to the polygon's boundary, similarly to Wachspress and discrete harmonic coordinates.

\section gbc_performance Performance

Apart from the most important requirement on barycentric coordinates to be as precise as possible, it is very important for them to be as fast as possible to evaluate. These coordinates are used in many applications where they must be computed for millions of points and, thus, the real time usage of coordinates is crucial. When writing the code, we tried to fulfil this important requirement, and in this section we present a few results about the computation times of the implemented coordinates.

The structure of the speed test that we ran for all functions consists of computing coordinate values (or weights) at >= 1 million strictly interior points with respect to some polygon (or triangle, or segment). At each iteration of the loop we create a query point, pass it to the function, and compute all the related coordinates. We run this loop 10 times in a row, and the time presented in the log-log scale plot at the end of the section is the arithmetic mean of all trials.

A typical example of this performance test for triangle coordinates with reduced number of query points can be found below. This example also illustrates how to construct an iterator and pass it to the class. In this example we create an iterator that writes coordinate values for each new query point over coordinate values of the previous point in the fixed-size standard C++ array, so that memory is allocated only once.

\cgalExample{Barycentric_coordinates_2/Triangle_coordinates_speed_test.cpp}

The time to compute coordinates depends on many factors such as memory allocation, input kernel, output container, number of points, etc. In our tests we used the most standard C++ and \cgal features with minimum memory allocation. Therefore, the final time presented is the average time that can be expected without deep optimization but still with efficient memory allocation. It also means that it may vary depending on the usage of the package.

For all tests we used a MacBook Pro 2011 with 2 GHz Intel Core i7 processor (2 cores) and 8 GB 1333 MHz DDR3 memory. The installed operating system was OS X 10.9 Maverick. In order to compile the speed test suite, we used the Clang 5.0 64bit compiler. The resulting timings can be found in the figure below.

\cgalFigureBegin{time,time.png}
Time in seconds to compute \f$n\f$ coordinate values for a polygon with \f$n\f$ vertices at 1 million points with the fast \f$O(n)\f$ algorithms (dashed) and the slow \f$0(n^2)\f$ algorithms (solid) for Wachspress (blue), discrete harmonic (red), and mean value (green) coordinates.
\cgalFigureEnd

From the figure above it is easy to see that the \f$O(n^2)\f$ algorithm is as fast as the \f$O(n)\f$ algorithm if we have a polygon with a small number of vertices. But as the number of vertices is increased, the linear algorithm outperforms the squared one, as expected. One of the reasons for this behaviour is that for a small number of vertices the multiplications for \f$n-2\f$ elements inside the \f$O(n^2)\f$ algorithm with the fast \f$O(n)\f$ algorithms (dashed) and the slow \f$O(n^2)\f$ algorithms (solid) take almost the same time as the corresponding division in the \f$O(n)\f$ algorithm. For a polygon with many vertices this multiplication is much slower.

\section gbc_implementation Implementation Details

The generic design of the package was developed in 2013 by Dmitry Anisimov and David Bommes with many useful comments by Kai Hormann and Pierre Alliez. The package consists of 6 classes, 2 enumerations, and one namespace. Appropriate iterators are used to provide an efficient access to data and to pass them to one of the generic algorithms for computing coordinates. Once instantiated for a polygon (triangle, segment), the coordinates can be computed multiple times for different query points with respect to all the vertices of the provided polygon (triangle, segment). All the classes are fully templated and have a simple and similar design. In particular, we follow the same naming convention for all functions. Yet, the number of functions can differ from one class to another. 

The implemented algorithms for computing coordinates do not depend on a particular kernel, and all the coordinates can be computed exactly, if an exact kernel is used, apart from mean value coordinates. The latter coordinates involve a square root operation, which results in a slightly worse precision with exact data types due to temporal conversion into a floating point type. The computed coordinates can be stored in an arbitrary container if an appropriate <a href="https://en.cppreference.com/w/cpp/named_req/OutputIterator">output iterator</a> is provided.

It is worth noting that the class `CGAL::Barycentric_coordinates::Segment_coordinates_2` is used to compute generalized barycentric coordinates along the polygon's boundary. Hence, one can use the trick for segment coordinates from Section \ref gbc_degeneracies if one is convinced that a point must lie exactly on the polygon's boundary but due to some numerical instabilities it does not.

The package is implemented in a way that later, if needed, other two-dimensional generalized barycentric coordinates can be easily added to this package.  

\section gbc_theory Theory of 2D Generalized Barycentric Coordinates

In 1827, the German mathematician and theoretical astronomer <a href="https://en.wikipedia.org/wiki/August_Ferdinand_Möbius">August Ferdinand Möbius</a> (1790--1868) proposed a method \cite cgal:bc:m-dbc-27  to find coordinates of a point in the plane with respect to the vertices of a triangle. These coordinates are called <a href="http://mathworld.wolfram.com/BarycentricCoordinates.html">triangle barycentric coordinates</a> (sometimes <a href="https://en.wikipedia.org/wiki/Barycentric_coordinate_system">area coordinates</a>), and they are widely used in a variety of applications. Some of these applications are linear interpolation over a triangle and a triangle inclusion test. The first one is used for so-called <a href="https://en.wikipedia.org/wiki/Shading">shading</a>, and the second one arises in the <a href="https://en.wikipedia.org/wiki/Rasterization">rasterization</a> step when an image in vector graphics format needs to be converted into a raster image. 

Triangle barycentric coordinates have many important properties, including \em constant and <em>linear precision</em>, <em> the Lagrange property</em>, and <em>positivity inside a triangle</em>. These properties make these coordinates a unique tool in many scientific fields. If we restrict triangle coordinates to one of the edges of a triangle and its supporting line, we get barycentric coordinates with respect to a segment and call them \ref compute_seg_coord "segment coordinates".

Let us show a couple of plots for the coordinates described above. To plot segment coordinates, we take a line \f$y = 0.4\f$ and define \ref fig__seg__example "a segment" \f$[v_0, v_1]\f$ on this line. Then we sample this segment and compute segment coordinates for all the sample points. If we plot the segment coordinate function at all the defined points with respect to the vertex \f$v_1\f$, we get the blue line depicted in the figure below. It grows from zero at the vertex \f$v_0\f$ to one at the vertex \f$v_1\f$.

\cgalFigureBegin{seg__coord__interp,seg__coord__interp.png}
Segment coordinates (blue) for all the segment points (green) with respect to the vertex \f$v_1 = (2.0,\ 0.4)\f$.
\cgalFigureEnd

If we want to plot triangle coordinates, we follow a similar approach. We take \ref fig__tri__example "a triangle" \f$[v_0, v_1, v_2]\f$ in the plane and sample its interior and boundary with a number of points. Once we have this sampling, we plot one of the triangle coordinate functions (here with respect to the third vertex of the triangle) at all the defined sample points. Likewise, we can plot the coordinate function with respect to the first or second vertex. The resulting function is linear (shown in the figure below) that grows from zero along the first edge \f$[v_0, v_1]\f$ to one at the chosen vertex \f$v_2\f$.

\cgalFigureBegin{tri__coord__interp,tri__coord__interp.png}
Triangle coordinates with respect to \f$v_2 = (1.0,\ 2.0)\f$. The colour bar indicates the range of values for the chosen coordinate.
\cgalFigureEnd

Since many applications require to work with more complex planar geometric shapes than segments and triangles, it seems natural to investigate a generalized version of triangle coordinates with respect to arbitrary polygons. The first attempt was taken in 1975 by E. L. Wachspress \cite cgal:bc:w-rfeb-75, and the resulting generalized barycentric coordinates are now called Wachspress coordinates \cite cgal:bc:mlbd-gbcip-02. \ref gbc_deg_wachspress_coordinates "These coordinates" are well-defined for arbitrary <em>strictly convex polygons</em> and have all the properties of triangle coordinates \cite cgal:bc:fhk-gcbcocp-06. Unfortunately, they are not well-defined for weakly convex and concave polygons. 

Analogously to the previous cases, we want to plot the Wachspress coordinates and see how they look like. Let us choose a \ref wp_polygon "non-regular hexagon", slightly rotate it, and move one of its vertices towards the line through its two adjacent neighbours. We sample the interior and the boundary of this polygon as before and plot the coordinate function with respect to the vertex that we moved at all the sample points. We see that we get a smooth function, which is linear along all edges and grows from zero to one, as the colour bar indicates.

\anchor wp_plot
\cgalFigureBegin{wp__coord__interp,wp__coord__interp.png}
The Wachspress coordinate function with respect to the indicated vertex with values from zero to one as the colour bar indicates.
\cgalFigureEnd

Another type of generalized barycentric coordinates goes back to Pinkall and Polthier in 1993 \cite cgal:pp-cdmsc-93 and Eck et al. in 1995 \cite cgal:bc:eddhls-maam-95 in the context of \ref PkgSurfaceMeshParameterization "triangle mesh parameterization". They are called discrete harmonic coordinates. \ref gbc_deg_discrete_harmonic_coordinates "These coordinates" are well-defined, similarly to Wachspress coordinates, for arbitrary <em>strictly convex polygons</em> and inherit all the properties of triangle coordinates <em>apart from the positivity inside a polygon</em> because they can take on negative values \ref gbc_deg_discrete_harmonic_coordinates "for some polygons". Another interesting property of these coordinate functions is that they coincide with Wachspress coordinates for any polygon whose vertices lie on a common circle.

To plot discrete harmonic coordinates we take \ref wp_plot "the same polygon" as for Wachspress coordinates and plot the coordinate function with respect to the same vertex. Again, we get a smooth function, which is linear along all edges and grows from zero to one. Isolines in the plot show the difference between discrete harmonic and Wachspress coordinates for the chosen polygon and vertex.

\anchor dh_plot
\cgalFigureBegin{dh__coord__interp,dh__coord__interp.png}
The discrete harmonic coordinate function with respect to the indicated vertex with values from zero to one as the colour bar indicates.
\cgalFigureEnd

The last type of generalized barycentric coordinates that we discuss are mean value coordinates \cite cgal:f-mvc-03 proposed by M. Floater in 2003. Based on the <a href="https://en.wikipedia.org/wiki/Mean_value_theorem">mean value theorem</a>, \ref gbc_deg_mean_value_coordinates "these coordinates", unlike Wachspress and discrete harmonic coordinates, are well-defined for arbitrary <em>simple polygons</em>, inherit all the properties of triangle coordinates for any convex polygon, and <em>lack only the positivity property for general concave polygons</em>. Hormann and Floater prove in \cite cgal:bc:hf-mvcapp-06 that these coordinates are positive inside the kernel of a <a href="https://en.wikipedia.org/wiki/Star-shaped_polygon">star-shaped polygon</a>. They are also positive in the closure of any quadrilateral. Like discrete harmonic weights, mean value weights are often used in the context of \ref PkgSurfaceMeshParameterization "triangle mesh parameterization."

In order to show the particular behaviour of mean value coordinates with an application to concave polygons, we take \ref fig__mv__example "a star-shaped polygon" with ten vertices \f$[v_0, \dots, v_9]\f$, sample its interior and boundary, and plot the coordinate function with respect to the fourth vertex \f$v_3\f$. As the colour bar indicates, the obtained function grows from a slightly negative value to one at the chosen vertex. It is also smooth inside the polygon and linear along all edges.

\cgalFigureBegin{mv__coord__interp,mv__coord__interp.png}
Mean value coordinates with respect to \f$v_3\f$. The colour bar indicates the range of values for the chosen coordinate function.
\cgalFigureEnd

<b>Interesting fact</b>: all the coordinates discussed in this section and implemented in the package come from one and the same family of generalized barycentric coordinates named <em>3-point family of coordinates</em> \cite cgal:bc:fhk-gcbcocp-06. 

\section gbc_acknowledgments Acknowledgments
The authors wish to thank <a href="https://www.inf.usi.ch/phd/schneider/">Teseo Schneider</a> and <a href="https://search.usi.ch/people/5ae37d3d990b431a02b95b0b606da2e6/Schaerfig-Randolf">Randolf Schaerfig</a> for helpful comments and discussions. We also appreciate the great effort invested in this package by our reviewers <a href="https://geometryfactory.com/who-we-are/">Andreas Fabri and Sébastien Loriot</a>. Finally, to create pictures for this manual, we used two programs: <a href="https://www.geogebra.org">Geogebra</a> and <a href="https://www.mathworks.com/products/matlab.html">Matlab</a>. 

*/

}
