% +------------------------------------------------------------------------+
% | Reference manual page: linear_interpolation.tex
% +------------------------------------------------------------------------+
% | 
% | August 2003  Julia Floetotto
% | Package:   Interpolation
% | 
% |
% +------------------------------------------------------------------------+

\begin{ccRefFunction}{linear_interpolation}

\ccDefinition
  
The function \ccRefName\ computes the weighted sum of the function
values which must be provided via a functor.


\ccInclude{CGAL/interpolation_functions.h}

\ccFunction{template < class ForwardIterator, class Functor> typename
  Functor::result_type::first_type linear_interpolation(ForwardIterator first,
  ForwardIterator beyond, const typename
  std::iterator_traits<ForwardIterator>::value_type::second_type&
  norm, Functor function_values);}{\ccc{ForwardIterator::value_type}
  is a pair associating a point to a (non-normalized) barycentric
  coordinate.  \ccc{norm} is the normalization factor. Given a point,
  the functor \ccc{function_values} allows to access a pair of a
  function value and a Boolean. The Boolean indicates whether the
  function value could be retrieved correctly. This function generates
  the interpolated function value as the weighted sum of the values
  corresponding to each point of the point/coordinate pairs in the
  range $\left[\right.$\ccc{first}, \ccc{beyond}$\left.\right)$.
  \ccPrecond{\ccc{norm} $\neq 0$. 
  \ccc{function_value(p).second == true} for all
    points \ccc{p} of the point/coordinate pairs in the range
    $\left[\right.$\ccc{first}, \ccc{beyond}$\left.\right)$.}}
  \ccHeading{Requirements}
  \begin{enumerate}
  \item \ccc{ForwardIterator::value_type} is a pair of
    point/coordinate value, thus
    \ccc{ForwardIterator::value_type::first_type} is equivalent to a
    point and \ccc{ForwardIterator::value_type::second_type} is a
    field number type.
  \item \ccc{Functor::argument_type} must be equivalent to
    \ccc{ForwardIterator::value_type::first_type} and
    \ccc{Functor::result_type} is a pair of the function value type
    and a Boolean value. The function value type must provide a
    multiplication and addition operation with the field number type
    \ccc{ForwardIterator::value_type::second_type} and a constructor
    with argument $0$. A model of the functor is provided by the
    struct \ccc{Data_access}. It must be instantiated accordingly with
    an associative container (e.g.\ \stl\ \ccc{std::map}) having the
    point type as \ccc{key_type} and the function value type as
    \ccc{mapped_type}.
  \end{enumerate}
  
  \ccSeeAlso
  \ccRefIdfierPage{CGAL::Data_access<Map>}\\
  %\ccRefIdfierPage{CGAL::sibson_c1_interpolation} \\
  %\ccRefIdfierPage{CGAL::sibson_gradient_fitting} \\
  %\ccRefIdfierPage{CGAL::farin_c1_interpolation} \\
  %\ccRefIdfierPage{CGAL::quadratic_interpolation} \\
  \ccRefIdfierPage{CGAL::natural_neighbor_coordinates_2}\\
  \ccRefIdfierPage{CGAL::regular_neighbor_coordinates_2} \\
  \ccRefIdfierPage{CGAL::surface_neighbor_coordinates_3}\\
                                %\ccImplementation 

\end{ccRefFunction}