%% ==============================================================
%% Specification: Computing Extremal Polygons
%% --------------------------------------------------------------
%% file  : spec_extremal_polygons.awi
%% author: Michael Hoffmann
%% $Id$
%% ==============================================================

\cgalColumnLayout

\begin{ccRefFunction}{maximum_area_inscribed_k_gon_2}
  \ccIndexMainItem[t]{largest inscribed polygon}
  \ccIndexSubitem[t]{polygon}{largest inscribed}
  \ccIndexSubitem[t]{triangle}{largest inscribed}
  
  \ccDefinition The function \ccRefName\ computes a maximum area
  $k$-gon $P_k$ that can be inscribed into a given convex polygon $P$.
  Note that
  \begin{itemize}
  \item $P_k$ is not unique in general, but it can be chosen in such a
    way that its vertices form a subset of the vertex set of $P$ and
  \item the vertices of a maximum area $k$-gon, where the $k$ vertices
    are to be drawn from a planar point set $S$, lie on the convex
    hull of $S$ i.e. a convex polygon.
  \end{itemize}

  \ccInclude{CGAL/extremal_polygon_2.h}

  \def\ccLongParamLayout{\ccTrue} 
  
  \ccGlobalFunction{
    template < class RandomAccessIterator, class OutputIterator >
    OutputIterator
    maximum_area_inscribed_k_gon_2(
    RandomAccessIterator points_begin,
    RandomAccessIterator points_end,
    int k,
    OutputIterator o);}
  
  computes a maximum area inscribed $k$-gon of the convex polygon
  described by [\ccc{points_begin}, \ccc{points_end}), writes its
  vertices to \ccc{o} and returns the past-the-end iterator of this
  sequence.
  
  \ccPrecond
  \begin{enumerate}
  \item the -- at least three -- points denoted by the range
    [\ccc{points_begin}, \ccc{points_end}) form the boundary of a
    convex polygon (oriented clock-- or counterclockwise).
  \item $k \ge 3$.
  \end{enumerate}
  
  \ccRequire
  \begin{enumerate}
  \item Value type of \ccc{RandomAccessIterator} is \ccc{K::Point_2}
    where \ccc{K} is a model for \ccc{Kernel}.
  \item \ccc{OutputIterator} accepts the value type of
    \ccc{RandomAccessIterator} as value type.
  \end{enumerate}

  \ccSeeAlso
  \ccRefIdfierPage{CGAL::maximum_perimeter_inscribed_k_gon_2}\\
  \ccRefConceptPage{ExtremalPolygonTraits_2}\\
  \ccRefIdfierPage{CGAL::Extremal_polygon_area_traits_2<K>}\\
  \ccRefIdfierPage{CGAL::Extremal_polygon_perimeter_traits_2<K>}\\
  \ccRefIdfierPage{CGAL::extremal_polygon_2}\\
  \ccRefIdfierPage{CGAL::monotone_matrix_search}
  
  \ccImplementation The implementation uses monotone matrix search
  \cite{akmsw-gamsa-87} and has a worst case running time of $O(k
  \cdot n + n \cdot \log n)$, where $n$ is the number of vertices in
  $P$.

  \ccExample The following code generates a random convex polygon
  \ccc{p} with ten vertices and computes the maximum area inscribed
  five-gon of \ccc{p}.

  \ccIncludeExampleCode{Matrix_search/extremal_polygon_2_example_area.cpp}

\end{ccRefFunction}

\begin{ccRefFunction}{maximum_perimeter_inscribed_k_gon_2}
  \ccIndexMainItem[t]{largest inscribed polygon}
  \ccIndexSubitem[t]{polygon}{largest inscribed}
  \ccIndexSubitem[t]{triangle}{largest inscribed}
  
  \ccDefinition The function \ccRefName\ computes a maximum perimeter
  $k$-gon $P_k$ that can be inscribed into a given convex polygon $P$.
  Note that
  \begin{itemize}
  \item $P_k$ is not unique in general, but it can be chosen in such a
    way that its vertices form a subset of the vertex set of $P$ and
  \item the vertices of a maximum perimeter $k$-gon, where the $k$
    vertices are to be drawn from a planar point set $S$, lie on the
    convex hull of $S$ i.e. a convex polygon.
  \end{itemize}

  \ccInclude{CGAL/extremal_polygon_2.h}

  \def\ccLongParamLayout{\ccTrue}
  \ccGlobalFunction{
    template < class RandomAccessIterator, class OutputIterator >
    OutputIterator
    maximum_perimeter_inscribed_k_gon_2(
    RandomAccessIterator points_begin,
    RandomAccessIterator points_end,
    int k,
    OutputIterator o);}
  
  computes a maximum perimeter inscribed $k$-gon of the convex polygon
  described by [\ccc{points_begin}, \ccc{points_end}), writes its
  vertices to \ccc{o} and returns the past-the-end iterator of this
  sequence.

  \ccPrecond
  \begin{enumerate}
  \item the -- at least three -- points denoted by the range
    [\ccc{points_begin}, \ccc{points_end}) form the boundary of a
    convex polygon (oriented clock-- or counterclockwise).
  \item $k \ge 2$.
  \end{enumerate}

  \ccRequire
  \begin{enumerate}
  \item Value type of \ccc{RandomAccessIterator} is \ccc{K::Point_2}
    where \ccc{K} is a model for \ccc{Kernel}.
  \item There is a global function \ccc{K::FT CGAL::sqrt(K::FT)}
    defined that computes the squareroot of a number.
  \item \ccc{OutputIterator} accepts the value type of
    \ccc{RandomAccessIterator} as value type.
  \end{enumerate}

  \ccTagDefaults

  \ccSeeAlso
  \ccRefIdfierPage{CGAL::maximum_area_inscribed_k_gon_2}\\
  \ccRefConceptPage{ExtremalPolygonTraits_2}\\
  \ccRefIdfierPage{CGAL::Extremal_polygon_area_traits_2<K>}\\
  \ccRefIdfierPage{CGAL::Extremal_polygon_perimeter_traits_2<K>}\\
  \ccRefIdfierPage{CGAL::extremal_polygon_2}\\
  \ccRefIdfierPage{CGAL::monotone_matrix_search}
  
  \ccImplementation The implementation uses monotone matrix search
  \cite{akmsw-gamsa-87} and has a worst case running time of $O(k
  \cdot n + n \cdot \log n)$, where $n$ is the number of vertices in
  $P$.

  \ccExample The following code generates a random convex polygon
  \ccc{p} with ten vertices and computes the maximum perimeter inscribed
  five-gon of \ccc{p}.

  \ccIncludeExampleCode{Matrix_search/extremal_polygon_2_example_perimeter.cpp}

\end{ccRefFunction}

\begin{ccRefFunction}{extremal_polygon_2}
  \begin{ccAdvanced}
    
    \ccDefinition The function \ccRefName\ computes a maximal $k$-gon
    that can be inscribed into a given convex polygon. The criterion
    for maximality and some basic operations have to be specified in
    an appropriate traits class parameter.
    
    \ccInclude{CGAL/extremal_polygon_2.h}

    \def\ccLongParamLayout{\ccTrue} 
    
    \ccGlobalFunction{
      template < class RandomAccessIterator, class OutputIterator, class Traits >
      OutputIterator
      extremal_polygon_2(
      RandomAccessIterator points_begin,
      RandomAccessIterator points_end,
      int k,
      OutputIterator o,
      const Traits& t);}
    
    computes a maximal (as specified by \ccc{t}) inscribed $k$-gon of
    the convex polygon described by [\ccc{points_begin},
    \ccc{points_end}), writes its vertices to \ccc{o} and returns the
    past-the-end iterator of this sequence.
    
    \ccPrecond
    \begin{enumerate}
    \item the -- at least three -- points denoted by the range
      [\ccc{points_begin}, \ccc{points_end}) form the boundary of a
      convex polygon (oriented clock-- or counterclockwise).
    \item $k \ge \ccc{t.min_k()}$.
    \end{enumerate}
    
    \ccRequire
    \begin{enumerate}
    \item \ccc{Traits} is a model for \ccc{ExtremalPolygonTraits_2}.
    \item Value type of \ccc{RandomAccessIterator} is \ccc{Traits::Point_2}.
    \item \ccc{OutputIterator} accepts \ccc{Traits::Point_2} as value
      type.
    \end{enumerate}

    \ccSeeAlso
    \ccRefIdfierPage{CGAL::maximum_area_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::maximum_perimeter_inscribed_k_gon_2}\\
    \ccRefConceptPage{ExtremalPolygonTraits_2}\\
    \ccRefIdfierPage{CGAL::monotone_matrix_search}
    
    \ccImplementation The implementation uses monotone matrix search
    \cite{akmsw-gamsa-87} and has a worst case running time of $O(k
    \cdot n + n \cdot \log n)$, where $n$ is the number of vertices in
    $P$.
  \end{ccAdvanced}
\end{ccRefFunction}

\begin{ccRefClass}{Extremal_polygon_area_traits_2<K>}
  \begin{ccAdvanced}
    \ccCreationVariable{t}\ccTagFullDeclarations
    
    \ccDefinition The class \ccClassName\ provides the types and
    operations needed to compute a maximum area $k$-gon $P_k$ that can
    be inscribed into a given convex polygon $P$ using the function
    \ccc{extremal_polygon_2}.
    
    \ccRequirements The template parameter \ccc{K} is a model for
    \ccc{Kernel}.
    
    \ccIsModel
    \ccRefConceptPage{ExtremalPolygonTraits_2}

    \ccTypes 
    
    \ccNestedType{FT}{typedef to \ccc{K::FT}.}
    
    \ccNestedType{Point_2}{typedef to \ccc{K::Point_2}.}
    
    \ccNestedType{Less_xy_2}{typedef to \ccc{K::Less_xy_2}.}
    
    \ccNestedType{Orientation_2}{typedef to \ccc{K::Orientation_2}.}
    
    \ccNestedType{Operation}{AdaptableBinaryFunction class \ccc{op}:
      \ccc{Point_2} $\times$ \ccc{Point_2} $\rightarrow$ \ccc{FT}.
      For a fixed \ccc{Point_2} $root$, \ccc{op}$(p,\,q)$ returns
      twice the area of the triangle $(root,\, q,\, p)$.}

    \ccOperations
    
    \ccMemberFunction{int min_k() const;}{returns 3.}
    
    \ccMemberFunction{FT init(const Point_2& p, const Point_2& q)
      const;}{returns \ccc{FT(0)}.}
    
    \ccMemberFunction{Operation operation( const Point_2& p)
      const;}{returns \ccc{Operation} where \ccc{p} is the fixed
      $root$ point.}
    
    \ccMemberFunction{template < class RandomAccessIterator, class
      OutputIterator > OutputIterator compute_min_k_gon(
      RandomAccessIterator points_begin, RandomAccessIterator points_end, FT&
      max_area, OutputIterator o) const;}{writes the vertices of
      [\ccc{points_begin}, \ccc{points_end}) forming a maximum area
      triangle rooted at \ccc{points_begin[0]} to o and returns the
      past-the-end iterator for that sequence (== \ccc{o + 3}).}
    
    \ccMemberFunction{Less_xy_2 less_xy_2_object();}{}
    
    \ccGlue\ccMemberFunction{Orientation_2 orientation_2_object();}{}
    
    \ccSeeAlso
    \ccRefIdfierPage{CGAL::maximum_area_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::maximum_perimeter_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::extremal_polygon_2}\\
    \ccRefIdfierPage{CGAL::Extremal_polygon_perimeter_traits_2<K>}\\
    \ccRefConceptPage{ExtremalPolygonTraits_2}

  \end{ccAdvanced}
\end{ccRefClass}    

\begin{ccRefClass}{Extremal_polygon_perimeter_traits_2<K>}
  \begin{ccAdvanced}
    \ccCreationVariable{t}\ccTagFullDeclarations
    
    \ccDefinition The class \ccClassName\ provides the types and
    operations needed to compute a maximum perimeter $k$-gon $P_k$
    that can be inscribed into a given convex polygon $P$ using the
    function \ccc{extremal_polygon_2}.
    
    \ccRequirements The template parameter \ccc{K} is a model for
    \ccc{Kernel}.
    
    \ccIsModel
    \ccRefConceptPage{ExtremalPolygonTraits_2}

    \ccTypes 
    
    \ccNestedType{FT}{typedef to \ccc{K::FT}.}
    
    \ccNestedType{Point_2}{typedef to \ccc{K::Point_2}.}
    
    \ccNestedType{Less_xy_2}{typedef to \ccc{K::Less_xy_2}.}
    
    \ccNestedType{Orientation_2}{typedef to \ccc{K::Orientation_2}.}
    
    \ccNestedType{Operation}{AdaptableBinaryFunction class \ccc{op}:
      \ccc{Point_2} $\times$ \ccc{Point_2} $\rightarrow$ \ccc{FT}.
      For a fixed \ccc{Point_2} $root$, \ccc{op}$(p,\,q)$ returns
      $d(r,\,p) + d(p,\,q) - d(r,\,q)$ where $d$ denotes the Euclidean
      distance.}

    \ccOperations
    
    \ccMemberFunction{int min_k() const;}{returns 2.}
    
    \ccMemberFunction{FT init(const Point_2& p, const Point_2& q)
      const;}{returns twice the Euclidean distance between \ccc{p} and
      \ccc{q}.}
    
    \ccMemberFunction{Operation operation( const Point_2& p)
      const;}{returns \ccc{Operation} where \ccc{p} is the fixed
      $root$ point.}
    
    \ccMemberFunction{template < class RandomAccessIterator, class
      OutputIterator > OutputIterator compute_min_k_gon(
      RandomAccessIterator points_begin, RandomAccessIterator points_end, FT&
      max_area, OutputIterator o) const;}{writes the pair
      (\ccc{points_begin[0]}, \ccc{p}) where \ccc{p} is drawn from
      [\ccc{points_begin}, \ccc{points_end}) such that the Euclidean
      distance between both points is maximized (maximum perimeter
      2-gon rooted at \ccc{points_begin[0]}) to o and returns the
      past-the-end iterator for that sequence (== \ccc{o + 2}).}
    
    \ccMemberFunction{Less_xy_2 less_xy_2_object();}{}
    
    \ccGlue\ccMemberFunction{Orientation_2 orientation_2_object();}{}
    
    \ccSeeAlso
    \ccRefIdfierPage{CGAL::maximum_area_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::maximum_perimeter_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::extremal_polygon_2}\\
    \ccRefIdfierPage{CGAL::Extremal_polygon_area_traits_2<K>}\\
    \ccRefConceptPage{ExtremalPolygonTraits_2}

  \end{ccAdvanced}
\end{ccRefClass}    

\begin{ccRefConcept}{ExtremalPolygonTraits_2}
  \begin{ccAdvanced}
    \ccCreationVariable{t}\ccTagFullDeclarations
    
    \ccDefinition The concept \ccRefName\ provides the types and
    operations needed to compute a maximal $k$-gon that can be
    inscribed into a given convex polygon.
    
    \ccTypes 
    
    \ccNestedType{FT}{model for \ccRefConceptPage{FieldNumberType}.}
    
    \ccNestedType{Point_2}{model for
      \ccRefConceptPage{Kernel::Point_2}.}
    
    \ccNestedType{Less_xy_2}{model for
      \ccRefConceptPage{Kernel::Less_xy_2}.}
    
    \ccNestedType{Orientation_2}{model for
      \ccRefConceptPage{Kernel::Orientation_2}.}
    
    \ccNestedType{Operation}{AdaptableBinaryFunction class \ccc{op}:
      \ccc{Point_2} $\times$ \ccc{Point_2} $\rightarrow$ \ccc{FT}.
      Together with \ccc{init} this operation recursively defines the
      objective function to maximize.  Let $p$ and $q$ be two vertices
      of a polygon $P$ such that $q$ precedes $p$ in the oriented
      vertex chain of $P$ starting with vertex $root$.  Then
      \ccc{op(p,q)} returns the value by which an arbitrary
      sub-polygon of $P$ with vertices from $[root,\, q]$ increases
      when $p$ is added to it. E.g. in the maximum area case this is
      the area of the triangle $(root,\, q,\, p)$.}

    \ccOperations
    
    \ccMemberFunction{int min_k() const;}{returns the minimal $k$ for
      which a maximal $k$-gon can be computed. (e.g. in the maximum
      area case this is three.)}
    
    \ccMemberFunction{FT init( const Point_2& p, const Point_2& q)
      const;}{returns the value of the objective function for a
      polygon consisting of the two points \ccc{p} and \ccc{q}. (e.g.
      in the maximum area case this is \ccc{FT( 0)}.)}
    
    \ccMemberFunction{Operation operation( const Point_2& p)
      const;}{return \ccc{Operation} where \ccc{p} is the fixed $root$
      point.}
    
    \ccMemberFunction{template < class RandomAccessIterator, class
      OutputIterator > OutputIterator compute_min_k_gon(
      RandomAccessIterator points_begin, RandomAccessIterator
      points_end, FT& max_area, OutputIterator o) const;}{writes the
      points of [\ccc{points_begin}, \ccc{points_end}) forming a
      \ccc{min_k()}-gon rooted at \ccc{points_begin[0]} of maximal
      value to o and returns the past-the-end iterator for that
      sequence (== \ccc{o + min_k()}).}
    
    \ccMemberFunction{Less_xy_2 less_xy_2_object();}{}
    
    \ccGlue\ccMemberFunction{Orientation_2 orientation_2_object();}{}
    
    \ccHeading{Notes}
    \begin{itemize}
    \item \ccClassName\ccc{::Less_xy_2} and
      \ccClassName\ccc{::Orientation_2} are used for (expensive)
      precondition checking only. Therefore, they need not to be
      specified, in case that precondition checking is disabled.
    \end{itemize}
    
    \ccHasModels
    \ccRefIdfierPage{CGAL::Extremal_polygon_area_traits_2<K>}\\
    \ccRefIdfierPage{CGAL::Extremal_polygon_perimeter_traits_2<K>}

    \ccSeeAlso
    \ccRefIdfierPage{CGAL::maximum_area_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::maximum_perimeter_inscribed_k_gon_2}\\
    \ccRefIdfierPage{CGAL::extremal_polygon_2}

  \end{ccAdvanced}
\end{ccRefConcept}    

%% --------------------------------------------------------------
%% EOF spec_extremal_polygons.awi
%% --------------------------------------------------------------