Add Inscribed_areas doc.

.gitattributes

@@ -2795,6 +2795,19 @@ HalfedgeDS/doc_tex/HalfedgeDS_ref/fig/hds_optional.gif -text svneol=unset#image/
 HalfedgeDS/doc_tex/HalfedgeDS_ref/fig/hds_optional.pdf -text svneol=unset#application/pdf
 HalfedgeDS/doc_tex/HalfedgeDS_ref/fig/hds_optional_small.gif -text svneol=unset#image/gif
 Inscribed_areas/demo/Largest_empty_rect_2/Qt3/help/index.html svneol=native#text/html
+Inscribed_areas/doc/Inscribed_areas/CGAL/Extremal_polygon_traits_2.h -text
+Inscribed_areas/doc/Inscribed_areas/CGAL/Largest_empty_iso_rectangle_2.h -text
+Inscribed_areas/doc/Inscribed_areas/CGAL/extremal_polygon_2.h -text
+Inscribed_areas/doc/Inscribed_areas/Concepts/ExtremalPolygonTraits_2.h -text
+Inscribed_areas/doc/Inscribed_areas/Concepts/LargestEmptyIsoRectangleTraits_2.h -text
+Inscribed_areas/doc/Inscribed_areas/Inscribed_areas.txt -text
+Inscribed_areas/doc/Inscribed_areas/PackageDescription.txt -text
+Inscribed_areas/doc/Inscribed_areas/fig/largestEmptyRect.gif -text svneol=unset#image/gif
+Inscribed_areas/doc/Inscribed_areas/fig/largestEmptyRect.pdf -text svneol=unset#application/pdf
+Inscribed_areas/doc/Inscribed_areas/fig/ler-detail.png -text svneol=unset#image/png
+Inscribed_areas/doc/Inscribed_areas/fig/ler.png -text svneol=unset#image/png
+Inscribed_areas/doc/Inscribed_areas/fig/max_triangle.gif -text svneol=unset#image/gif
+Inscribed_areas/doc/Inscribed_areas/fig/max_triangle.pdf -text svneol=unset#application/pdf
 Inscribed_areas/doc_tex/Inscribed_areas/largestEmptyRect.gif -text svneol=unset#image/gif
 Inscribed_areas/doc_tex/Inscribed_areas/largestEmptyRect.pdf -text svneol=unset#application/pdf
 Inscribed_areas/doc_tex/Inscribed_areas/max_triangle.gif -text svneol=unset#image/gif

Documentation/doxyassist.xml

@@ -760,8 +760,6 @@ namespace for the XML file to be processed properly.  -->
           <string name="STRIP_FROM_PATH">../GraphicsView/doc/GraphicsView/</string>
           <string name="STRIP_FROM_INC_PATH">../GraphicsView/doc/GraphicsView/</string>
           <string name="GENERATE_TAGFILE">./tags/GraphicsView.tag</string>
-          <!-- The path ../GraphicsView/examples does not exist currently. -->
-          <!-- <string name="EXAMPLE_PATH">../GraphicsView/examples</string> -->
           <string name="IMAGE_PATH">../GraphicsView/doc/GraphicsView/fig</string>
           <list name="TAGFILES" append="true">
           </list>
@@ -801,14 +799,8 @@ namespace for the XML file to be processed properly.  -->
           <string name="STRIP_FROM_PATH">../Polytope_distance_d/doc/Polytope_distance_d/</string>
           <string name="STRIP_FROM_INC_PATH">../Polytope_distance_d/doc/Polytope_distance_d/</string>
           <string name="GENERATE_TAGFILE">./tags/Polytope_distance_d.tag</string>
-          <list name="EXAMPLE_PATH" append="true">
-            <item>../Polytope_distance_d/examples</item>
-            <item>../Width_3/examples</item>
-            <item>../Matrix_search/examples</item>
-          </list>
+          <string name="EXAMPLE_PATH">../Polytope_distance_d/examples</string>
           <string name="IMAGE_PATH">../Polytope_distance_d/doc/Polytope_distance_d/fig</string>
-          <list name="TAGFILES" append="true">
-          </list>
         </doxygen>
       </project>
 
@@ -819,18 +811,23 @@ namespace for the XML file to be processed properly.  -->
           <string name="STRIP_FROM_PATH">../Bounding_volumes/doc/Bounding_volumes/</string>
           <string name="STRIP_FROM_INC_PATH">../Bounding_volumes/doc/Bounding_volumes/</string>
           <string name="GENERATE_TAGFILE">./tags/Bounding_volumes.tag</string>
-          <list name="EXAMPLE_PATH" append="true">
-            <item>../Min_quadrilateral_2/examples</item>
-            <item>../Min_circle_2/examples</item>
-            <item>../Min_ellipse_2/examples</item>
-            <item>../Min_sphere_d/examples</item>
-            <item>../Approximate_min_ellipsoid_d/examples</item>
-            <item>../Matrix_search/examples</item>
-          </list>
+          <string name="EXAMPLE_PATH">../Bounding_volumes/examples</string>
           <string name="IMAGE_PATH">../Bounding_volumes/doc/Bounding_volumes/fig</string>
         </doxygen>
       </project>
 
+      <project>
+        <name>Inscribed Areas</name>
+        <input>../Inscribed_areas/doc/Inscribed_areas</input>
+        <doxygen>
+          <string name="STRIP_FROM_PATH">../Inscribed_areas/doc/Inscribed_areas/</string>
+          <string name="STRIP_FROM_INC_PATH">../Inscribed_areas/doc/Inscribed_areas/</string>
+          <string name="GENERATE_TAGFILE">./tags/Inscribed_areas.tag</string>
+          <string name="EXAMPLE_PATH">../Inscribed_areas/examples</string>
+          <string name="IMAGE_PATH">../Inscribed_areas/doc/Inscribed_areas/fig</string>
+        </doxygen>
+      </project>
+
       <project>
         <name>2D Snap Rounding</name>
         <input>../Snap_rounding_2/doc/Snap_rounding_2</input>

Inscribed_areas/doc/Inscribed_areas/CGAL/Extremal_polygon_traits_2.h

@@ -0,0 +1,210 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgInscribedAreas
+
+\advanced The class `Extremal_polygon_area_traits_2` provides the types and 
+operations needed to compute a maximum area \f$ k\f$-gon \f$ P_k\f$ that can 
+be inscribed into a given convex polygon \f$ P\f$ using the function 
+`extremal_polygon_2`. 
+
+\tparam K must be a model of `Kernel`.
+
+\models ::ExtremalPolygonTraits_2 
+
+\sa `CGAL::maximum_area_inscribed_k_gon_2`
+\sa `CGAL::maximum_perimeter_inscribed_k_gon_2`
+\sa `CGAL::extremal_polygon_2`
+\sa `CGAL::Extremal_polygon_perimeter_traits_2<K>`
+\sa `ExtremalPolygonTraits_2` 
+
+*/
+template< typename K >
+class Extremal_polygon_area_traits_2 {
+public:
+
+/// \name Types 
+/// @{
+
+/*! 
+typedef to `K::FT`. 
+*/ 
+typedef Hidden_type FT; 
+
+/*! 
+typedef to `K::Point_2`. 
+*/ 
+typedef Hidden_type Point_2; 
+
+/*! 
+typedef to `K::Less_xy_2`. 
+*/ 
+typedef Hidden_type Less_xy_2; 
+
+/*! 
+typedef to `K::Orientation_2`. 
+*/ 
+typedef Hidden_type Orientation_2; 
+
+/*! 
+AdaptableBinaryFunction class `op`: 
+`Point_2` \f$ \times\f$ `Point_2` \f$ \rightarrow\f$ `FT`. 
+For a fixed `Point_2` \f$ root\f$, `op`\f$ (p,\,q)\f$ returns 
+twice the area of the triangle \f$ (root,\, q,\, p)\f$. 
+*/ 
+typedef Hidden_type Operation; 
+
+/// @} 
+
+/// \name Operations 
+/// @{
+
+/*! 
+returns 3. 
+*/ 
+int min_k() const; 
+
+/*! 
+returns `FT(0)`. 
+*/ 
+FT init(const Point_2& p, const Point_2& q) 
+const; 
+
+/*! 
+returns `Operation` where `p` is the fixed 
+\f$ root\f$ point. 
+*/ 
+Operation operation( const Point_2& p) 
+const; 
+
+/*! 
+writes the vertices of 
+[`points_begin`, `points_end`) forming a maximum area 
+triangle rooted at `points_begin[0]` to o and returns the 
+past-the-end iterator for that sequence (== `o + 3`). 
+*/ 
+template < class RandomAccessIterator, class 
+OutputIterator > OutputIterator compute_min_k_gon( 
+RandomAccessIterator points_begin, RandomAccessIterator points_end, FT& 
+max_area, OutputIterator o) const; 
+
+/*! 
+
+*/ 
+Less_xy_2 less_xy_2_object(); 
+
+/*! 
+
+*/ 
+Orientation_2 orientation_2_object(); 
+
+/// @}
+
+}; /* end Extremal_polygon_area_traits_2 */
+
+/*!
+\ingroup PkgInscribedAreas
+
+\advanced The class `Extremal_polygon_perimeter_traits_2` provides the
+types and operations needed to compute a maximum perimeter \f$
+k\f$-gon \f$ P_k\f$ that can be inscribed into a given convex polygon
+\f$ P\f$ using the function `extremal_polygon_2`.
+
+\tparam K must be a model of `Kernel`.
+
+\models ::ExtremalPolygonTraits_2 
+
+\sa `CGAL::maximum_area_inscribed_k_gon_2`
+\sa `CGAL::maximum_perimeter_inscribed_k_gon_2`
+\sa `CGAL::extremal_polygon_2`
+\sa `CGAL::Extremal_polygon_area_traits_2<K>`
+\sa `ExtremalPolygonTraits_2` 
+
+*/
+template< typename K >
+class Extremal_polygon_perimeter_traits_2 {
+public:
+
+/// \name Types 
+/// @{
+
+/*! 
+typedef to `K::FT`. 
+*/ 
+typedef Hidden_type FT; 
+
+/*! 
+typedef to `K::Point_2`. 
+*/ 
+typedef Hidden_type Point_2; 
+
+/*! 
+typedef to `K::Less_xy_2`. 
+*/ 
+typedef Hidden_type Less_xy_2; 
+
+/*! 
+typedef to `K::Orientation_2`. 
+*/ 
+typedef Hidden_type Orientation_2; 
+
+/*! 
+AdaptableBinaryFunction class `op`: 
+`Point_2` \f$ \times\f$ `Point_2` \f$ \rightarrow\f$ `FT`. 
+For a fixed `Point_2` \f$ root\f$, `op`\f$ (p,\,q)\f$ returns 
+\f$ d(r,\,p) + d(p,\,q) - d(r,\,q)\f$ where \f$ d\f$ denotes the Euclidean 
+distance. 
+*/ 
+typedef Hidden_type Operation; 
+
+/// @} 
+
+/// \name Operations 
+/// @{
+
+/*! 
+returns 2. 
+*/ 
+int min_k() const; 
+
+/*! 
+returns twice the Euclidean distance between `p` and 
+`q`. 
+*/ 
+FT init(const Point_2& p, const Point_2& q) 
+const; 
+
+/*! 
+returns `Operation` where `p` is the fixed 
+\f$ root\f$ point. 
+*/ 
+Operation operation( const Point_2& p) 
+const; 
+
+/*! 
+writes the pair 
+(`points_begin[0]`, `p`) where `p` is drawn from 
+[`points_begin`, `points_end`) such that the Euclidean 
+distance between both points is maximized (maximum perimeter 
+2-gon rooted at `points_begin[0]`) to o and returns the 
+past-the-end iterator for that sequence (== `o + 2`). 
+*/ 
+template < class RandomAccessIterator, class 
+OutputIterator > OutputIterator compute_min_k_gon( 
+RandomAccessIterator points_begin, RandomAccessIterator points_end, FT& 
+max_area, OutputIterator o) const; 
+
+/*! 
+
+*/ 
+Less_xy_2 less_xy_2_object(); 
+
+/*! 
+
+*/ 
+Orientation_2 orientation_2_object(); 
+
+/// @}
+
+}; /* end Extremal_polygon_perimeter_traits_2 */
+} /* end namespace CGAL */

Inscribed_areas/doc/Inscribed_areas/CGAL/Largest_empty_iso_rectangle_2.h

@@ -0,0 +1,186 @@
+
+namespace CGAL {
+
+/*!
+\ingroup PkgInscribedAreas
+
+Given a set of points in the plane, the class `Largest_empty_iso_rectangle_2` is a data 
+structure that maintains an iso-rectangle with the largest area among 
+all iso-rectangles that are inside a given bounding box( iso-rectangle), and 
+that do not contain any point of the point set. 
+
+The class `Largest_empty_iso_rectangle_2` expects a model of the concept `LargestEmptyIsoRectangleTraits_2` as its template argument. 
+
+Implementation 
+-------------- 
+
+The algorithm is an implementation of \cite o-naler-90. The runtime of an 
+insertion or a removal is \f$ O(\log n)\f$. A query takes \f$ O(n^2)\f$ worst 
+case time and \f$ O(n \log n)\f$ expected time. The working storage is \f$ 
+O(n)\f$. 
+
+*/
+template< typename T >
+class Largest_empty_iso_rectangle_2 {
+public:
+
+/// \name Types 
+/// @{
+
+/*! 
+
+*/ 
+typedef T Traits; 
+
+/*! 
+
+*/ 
+typedef Traits::Point_2 Point_2; 
+
+/*! 
+
+*/ 
+typedef Traits::Iso_rectangle_2 Iso_rectangle_2; 
+
+/*! 
+Iterator over the points. 
+
+This iterator allows to enumerate the points. It is non mutable,
+bidirectional and its value type is `Point_2`. It is invalidated by
+any insertion or removal of a point.
+*/ 
+typedef Hidden_type const_iterator; 
+
+/// @} 
+
+/// \name Creation 
+/// @{
+
+/*! 
+Constructor. The iso-rectangle `b` is the bounding rectangle. 
+*/ 
+Largest_empty_iso_rectangle_2<Traits> 
+(const Iso_rectangle_2 &b); 
+
+/*! 
+Constructor. The iso-rectangle whose lower left and upper right points are `p` and 
+`q` respectively is the bounding rectangle. 
+*/ 
+Largest_empty_iso_rectangle_2<Traits> 
+(const Point_2 p,const Point_2 q); 
+
+/*! 
+Constructor. The iso-rectangle whose lower left point and upper right points are (0,0) 
+and (1,1) respectively is the bounding rectangle. 
+*/ 
+Largest_empty_iso_rectangle_2<Traits> 
+(); 
+
+/*! 
+Copy constructor. 
+*/ 
+Largest_empty_iso_rectangle_2<Traits> 
+(const Largest_empty_iso_rectangle_2<Traits> tr); 
+
+/// @} 
+
+/// \name Assignment 
+/// @{
+
+/*! 
+
+*/ 
+Largest_empty_iso_rectangle_2<T> 
+operator=(const Largest_empty_iso_rectangle_2<T> & tr); 
+
+/// @} 
+
+/// \name Access Functions 
+/// @{
+
+/*! 
+Returns a const reference to the traits object. 
+*/ 
+const Traits & traits() const; 
+
+/*! 
+Returns an iterator to the beginning of the point set. 
+*/ 
+const_iterator begin() const; 
+
+/*! 
+Returns a past-the-end iterator for the point set. 
+*/ 
+const_iterator end() const; 
+
+/// @} 
+
+/// \name Queries 
+/// @{
+
+/*! 
+Returns the four points that define the largest empty iso-rectangle. 
+(Note that these points are not necessarily on a corner of an iso-rectangle.) 
+*/ 
+Quadruple<Point_2, Point_2, Point_2, Point_2> 
+get_left_bottom_right_top(); 
+
+/*! 
+Returns the largest empty iso-rectangle. (Note that the two 
+points defining the iso-rectangle are not necessarily part of 
+the point set.) 
+*/ 
+Iso_rectangle_2 get_largest_empty_iso_rectangle(); 
+
+/*! 
+Returns the iso-rectangle passed in the constructor. 
+*/ 
+Iso_rectangle_2 get_bounding_box(); 
+
+/// @} 
+
+/// \name Insertion 
+/// @{
+
+/*! 
+Inserts point `p` in the point set, if it is not already in the set. 
+*/ 
+void 
+insert(const Point_2& p); 
+
+/*! 
+Inserts point `p` in the point set, if it is not already in the set. 
+*/ 
+void 
+push_back(const Point_2& p); 
+
+/*! 
+Inserts the points in the range \f$ \left[\right.\f$`first`, 
+`last`\f$ \left.\right)\f$. Returns the number of inserted points. 
+
+\requires The `value_type` of `first` and `last` is `Point`.
+*/ 
+template < class InputIterator > 
+int 
+insert(InputIterator first, InputIterator last); 
+
+/// @} 
+
+/// \name Removal 
+/// @{
+
+/*! 
+Removes point `p`. 
+Returns false iff `p` is not in the point set. 
+*/ 
+bool remove(const Point_2& p); 
+
+/*! 
+Removes all points of `l`. 
+*/ 
+void clear(); 
+
+/// @}
+
+}; /* end Largest_empty_iso_rectangle_2 */
+} /* end namespace CGAL */

Inscribed_areas/doc/Inscribed_areas/CGAL/extremal_polygon_2.h

@@ -0,0 +1,199 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgInscribedAreas
+
+\advanced The function `extremal_polygon_2` computes a maximal \f$
+k\f$-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.
+
+computes a maximal (as specified by `t`) inscribed \f$ k\f$-gon of 
+the convex polygon described by [`points_begin`, 
+`points_end`), writes its vertices to `o` and returns the 
+past-the-end iterator of this sequence. 
+
+\pre <OL> 
+<LI>the - at least three - points denoted by the range 
+[`points_begin`, `points_end`) form the boundary of a 
+convex polygon (oriented clock- or counterclockwise). 
+<LI>\f$ k \ge \ccc{t.min_k()}\f$. 
+</OL> 
+
+\require <OL> 
+<LI>`Traits` is a model for `ExtremalPolygonTraits_2`. 
+<LI>Value type of `RandomAccessIterator` is `Traits::Point_2`. 
+<LI>`OutputIterator` accepts `Traits::Point_2` as value 
+type. 
+</OL> 
+
+\sa `CGAL::maximum_area_inscribed_k_gon_2`
+\sa `CGAL::maximum_perimeter_inscribed_k_gon_2`
+\sa `ExtremalPolygonTraits_2` 
+\sa `CGAL::monotone_matrix_search`
+
+Implementation 
+-------------- 
+
+The implementation uses monotone matrix search 
+\cite akmsw-gamsa-87 and has a worst case running time of \f$ O(k 
+\cdot n + n \cdot \log n)\f$, where \f$ n\f$ is the number of vertices in 
+\f$ P\f$. 
+
+*/
+
+template < class RandomAccessIterator, class OutputIterator, class Traits >
+OutputIterator
+extremal_polygon_2(
+RandomAccessIterator points_begin,
+RandomAccessIterator points_end,
+int k,
+OutputIterator o,
+const Traits& t);
+
+} /* namespace CGAL */
+
+namespace CGAL {
+
+/*!
+\ingroup PkgInscribedAreas
+
+The function `maximum_area_inscribed_k_gon_2` computes a maximum area 
+\f$ k\f$-gon \f$ P_k\f$ that can be inscribed into a given convex polygon \f$ P\f$. 
+Note that 
+<UL> 
+<LI>\f$ P_k\f$ 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 \f$ P\f$ and 
+<LI>the vertices of a maximum area \f$ k\f$-gon, where the \f$ k\f$ vertices 
+are to be drawn from a planar point set \f$ S\f$, lie on the convex 
+hull of \f$ S\f$ i.e. a convex polygon. 
+</UL> 
+
+computes a maximum area inscribed \f$ k\f$-gon of the convex polygon 
+described by [`points_begin`, `points_end`), writes its 
+vertices to `o` and returns the past-the-end iterator of this 
+sequence. 
+
+\pre <OL> 
+<LI>the - at least three - points denoted by the range 
+[`points_begin`, `points_end`) form the boundary of a 
+convex polygon (oriented clock- or counterclockwise). 
+<LI>\f$ k \ge 3\f$. 
+</OL> 
+
+\require <OL> 
+<LI>Value type of `RandomAccessIterator` is `K::Point_2` 
+where `K` is a model for `Kernel`. 
+<LI>`OutputIterator` accepts the value type of 
+`RandomAccessIterator` as value type. 
+</OL> 
+
+\sa `CGAL::maximum_perimeter_inscribed_k_gon_2`
+\sa `ExtremalPolygonTraits_2` 
+\sa `CGAL::Extremal_polygon_area_traits_2<K>`
+\sa `CGAL::Extremal_polygon_perimeter_traits_2<K>`
+\sa `CGAL::extremal_polygon_2`
+\sa `CGAL::monotone_matrix_search`
+
+Implementation 
+-------------- 
+
+The implementation uses monotone matrix search 
+\cite akmsw-gamsa-87 and has a worst case running time of \f$ O(k 
+\cdot n + n \cdot \log n)\f$, where \f$ n\f$ is the number of vertices in 
+\f$ P\f$. 
+
+Example 
+-------------- 
+
+The following code generates a random convex polygon 
+`p` with ten vertices and computes the maximum area inscribed 
+five-gon of `p`. 
+
+\cgalexample{extremal_polygon_2_area.cpp} 
+
+*/
+
+template < class RandomAccessIterator, class OutputIterator >
+OutputIterator
+maximum_area_inscribed_k_gon_2(
+RandomAccessIterator points_begin,
+RandomAccessIterator points_end,
+int k,
+OutputIterator o);
+
+} /* namespace CGAL */
+
+namespace CGAL {
+
+/*!
+\ingroup PkgInscribedAreas
+
+The function `maximum_perimeter_inscribed_k_gon_2` computes a maximum perimeter 
+\f$ k\f$-gon \f$ P_k\f$ that can be inscribed into a given convex polygon \f$ P\f$. 
+Note that 
+<UL> 
+<LI>\f$ P_k\f$ 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 \f$ P\f$ and 
+<LI>the vertices of a maximum perimeter \f$ k\f$-gon, where the \f$ k\f$ 
+vertices are to be drawn from a planar point set \f$ S\f$, lie on the 
+convex hull of \f$ S\f$ i.e. a convex polygon. 
+</UL> 
+
+computes a maximum perimeter inscribed \f$ k\f$-gon of the convex polygon 
+described by [`points_begin`, `points_end`), writes its 
+vertices to `o` and returns the past-the-end iterator of this 
+sequence. 
+
+\pre <OL> 
+<LI>the - at least three - points denoted by the range 
+[`points_begin`, `points_end`) form the boundary of a 
+convex polygon (oriented clock- or counterclockwise). 
+<LI>\f$ k \ge 2\f$. 
+</OL> 
+
+\require <OL> 
+<LI>Value type of `RandomAccessIterator` is `K::Point_2` 
+where `K` is a model for `Kernel`. 
+<LI>There is a global function `K::FT CGAL::sqrt(K::FT)` 
+defined that computes the squareroot of a number. 
+<LI>`OutputIterator` accepts the value type of 
+`RandomAccessIterator` as value type. 
+</OL> 
+
+\sa `CGAL::maximum_area_inscribed_k_gon_2`
+\sa `ExtremalPolygonTraits_2` 
+\sa `CGAL::Extremal_polygon_area_traits_2<K>`
+\sa `CGAL::Extremal_polygon_perimeter_traits_2<K>`
+\sa `CGAL::extremal_polygon_2`
+\sa `CGAL::monotone_matrix_search`
+
+Implementation 
+-------------- 
+
+The implementation uses monotone matrix search 
+\cite akmsw-gamsa-87 and has a worst case running time of \f$ O(k 
+\cdot n + n \cdot \log n)\f$, where \f$ n\f$ is the number of vertices in 
+\f$ P\f$. 
+
+Example 
+-------------- 
+
+The following code generates a random convex polygon 
+`p` with ten vertices and computes the maximum perimeter inscribed 
+five-gon of `p`. 
+
+\cgalexample{extremal_polygon_2_perimeter.cpp} 
+
+*/
+
+template < class RandomAccessIterator, class OutputIterator >
+OutputIterator
+maximum_perimeter_inscribed_k_gon_2(
+RandomAccessIterator points_begin,
+RandomAccessIterator points_end,
+int k,
+OutputIterator o);
+
+} /* namespace CGAL */
+

Inscribed_areas/doc/Inscribed_areas/Concepts/ExtremalPolygonTraits_2.h

@@ -0,0 +1,119 @@
+
+/*!
+\ingroup PkgInscribedAreasConcepts
+\cgalconcept
+
+\advanced The concept `ExtremalPolygonTraits_2` provides the types and
+operations needed to compute a maximal \f$ k\f$-gon that can be
+inscribed into a given convex polygon.
+
+\note `ExtremalPolygonTraits_2``::Less_xy_2` and 
+`ExtremalPolygonTraits_2``::Orientation_2` are used for (expensive) 
+precondition checking only. Therefore, they need not to be 
+specified, in case that precondition checking is disabled. 
+
+\hasModel `CGAL::Extremal_polygon_area_traits_2<K>`
+\hasModel `CGAL::Extremal_polygon_perimeter_traits_2<K>`
+
+\sa `CGAL::maximum_area_inscribed_k_gon_2`
+\sa `CGAL::maximum_perimeter_inscribed_k_gon_2`
+\sa `CGAL::extremal_polygon_2`
+
+*/
+
+class ExtremalPolygonTraits_2 {
+public:
+
+/// \name Types 
+/// @{
+
+/*! 
+model for `FieldNumberType`. 
+*/ 
+typedef Hidden_type FT; 
+
+/*! 
+model for 
+`Kernel::Point_2`. 
+*/ 
+typedef Hidden_type Point_2; 
+
+/*! 
+model for 
+`Kernel::Less_xy_2`. 
+*/ 
+typedef Hidden_type Less_xy_2; 
+
+/*! 
+model for 
+`Kernel::Orientation_2`. 
+*/ 
+typedef Hidden_type Orientation_2; 
+
+/*! 
+AdaptableBinaryFunction class `op`: 
+`Point_2` \f$ \times\f$ `Point_2` \f$ \rightarrow\f$ `FT`. 
+Together with `init` this operation recursively defines the 
+objective function to maximize. Let \f$ p\f$ and \f$ q\f$ be two vertices 
+of a polygon \f$ P\f$ such that \f$ q\f$ precedes \f$ p\f$ in the oriented 
+vertex chain of \f$ P\f$ starting with vertex \f$ root\f$. Then 
+`op(p,q)` returns the value by which an arbitrary 
+sub-polygon of \f$ P\f$ with vertices from \f$ [root,\, q]\f$ increases 
+when \f$ p\f$ is added to it. E.g. in the maximum area case this is 
+the area of the triangle \f$ (root,\, q,\, p)\f$. 
+*/ 
+typedef Hidden_type Operation; 
+
+/// @} 
+
+/// \name Operations 
+/// @{
+
+/*! 
+returns the minimal \f$ k\f$ for 
+which a maximal \f$ k\f$-gon can be computed. (e.g. in the maximum 
+area case this is three.) 
+*/ 
+int min_k() const; 
+
+/*! 
+returns the value of the objective function for a 
+polygon consisting of the two points `p` and `q`. (e.g. 
+in the maximum area case this is `FT( 0)`.) 
+*/ 
+FT init( const Point_2& p, const Point_2& q) 
+const; 
+
+/*! 
+return `Operation` where `p` is the fixed \f$ root\f$ 
+point. 
+*/ 
+Operation operation( const Point_2& p) 
+const; 
+
+/*! 
+writes the 
+points of [`points_begin`, `points_end`) forming a 
+`min_k()`-gon rooted at `points_begin[0]` of maximal 
+value to o and returns the past-the-end iterator for that 
+sequence (== `o + min_k()`). 
+*/ 
+template < class RandomAccessIterator, class 
+OutputIterator > OutputIterator compute_min_k_gon( 
+RandomAccessIterator points_begin, RandomAccessIterator 
+points_end, FT& max_area, OutputIterator o) const; 
+
+/*! 
+
+*/ 
+Less_xy_2 less_xy_2_object(); 
+
+/*! 
+
+*/ 
+Orientation_2 orientation_2_object(); 
+
+/// @}
+
+}; /* end ExtremalPolygonTraits_2 */
+

Inscribed_areas/doc/Inscribed_areas/Concepts/LargestEmptyIsoRectangleTraits_2.h

@@ -0,0 +1,128 @@
+
+/*!
+\ingroup PkgInscribedAreasConcepts
+\cgalconcept
+
+The concept `LargestEmptyIsoRectangleTraits_2` describes the set of requirements to be 
+fulfilled by any class used to instantiate the template parameter of 
+the class `Largest_empty_iso_rectangle_2<T>`. 
+This concept provides the types of the geometric primitives used in 
+this class and some function object types for the required 
+predicates on those primitives. 
+
+\hasModel CGAL::Cartesian<R> 
+\hasModel CGAL::Homogeneous<R> 
+
+\sa `CGAL::Largest_empty_iso_rectangle_2<Traits>` 
+
+*/
+
+class LargestEmptyIsoRectangleTraits_2 {
+public:
+
+/// \name Types 
+/// @{
+
+/*! 
+The point type. 
+*/ 
+typedef Hidden_type Point_2; 
+
+/*! 
+The iso rectangle type. 
+*/ 
+typedef Hidden_type Iso_rectangle_2; 
+
+/*! 
+Predicate object. Must provide 
+the operator 
+`Comparison_result operator()(Point_2 p, Point_2 q)` 
+which returns 
+`SMALLER, EQUAL` or `LARGER` 
+according ding to the 
+\f$ x\f$-ordering of points `p` and `q`. 
+*/ 
+typedef Hidden_type Compare_x_2; 
+
+/*! 
+Predicate object. Must provide 
+the operator 
+`Comparison_result operator()(Point_2 p, Point_2 q)` 
+which returns 
+`SMALLER, EQUAL` or `LARGER` 
+according to the 
+\f$ y\f$-ordering of points `p` and `q`. 
+*/ 
+typedef Hidden_type Compare_y_2; 
+
+/*! 
+Predicate object. Must provide 
+the operator 
+`bool operator()(Point_2 p, Point_2 q)` 
+which returns 
+whether `p` is less than `q` according to their \f$ x\f$-ordering. 
+*/ 
+typedef Hidden_type Less_x_2; 
+
+/*! 
+Predicate object. Must provide 
+the operator 
+`bool operator()(Point_2 p, Point_2 q)` 
+which returns 
+whether `p` is less than `q` according to their \f$ y\f$-ordering. 
+*/ 
+typedef Hidden_type Less_y_2; 
+
+/// @} 
+
+/// \name Creation 
+/// Only a default constructor, copy constructor and an assignement
+/// operator are required. Note that further constructors can be
+/// provided.
+/// @{
+
+/*! 
+Default constructor. 
+*/ 
+LargestEmptyIsoRectangleTraits_2(); 
+
+/*! 
+Copy constructor 
+*/ 
+LargestEmptyIsoRectangleTraits_2(LargestEmptyIsoRectangleTraits_2); 
+
+/*! 
+Assignment operator. 
+*/ 
+LargestEmptyIsoRectangleTraits_2 operator=(LargestEmptyIsoRectangleTraits_2 gtr); 
+
+/// @} 
+
+/// \name Predicate functions 
+/// The following functions give access to the predicate and constructor objects.
+/// @{
+
+/*! 
+
+*/ 
+Compare_x_2 compare_x_2_object(); 
+
+/*! 
+
+*/ 
+Compare_y_2 compare_y_2_object(); 
+
+/*! 
+
+*/ 
+Less_x_2 less_x_2_object(); 
+
+/*! 
+
+*/ 
+Less_y_2 less_y_2_object(); 
+
+/// @}
+
+}; /* end LargestEmptyIsoRectangleTraits_2 */
+

Inscribed_areas/doc/Inscribed_areas/Inscribed_areas.txt

@@ -0,0 +1,48 @@
+
+\page chapInscribedAreas Inscribed Areas 
+
+namespace CGAL {
+/*!
+
+\mainpage Inscribed Areas 
+\anchor chapInscribedAreas
+
+\authors Michael Hoffmann and Eli Packer 
+
+This chapter describes algorithms which for a given point set compute
+the ``best'' inscribed object from a specific
+class. We provide algorithms for
+computing maximal inscribed \f$ k\f$-gons (triangles, quadrilaterals,
+\f$ \dots\f$ ) of a planar point set \f$ P\f$. Maximal \f$ k\f$-gons are convex, and it
+is known that their vertices can be chosen to be vertices of the
+convex hull of \f$ P\f$. Hence, the functions
+`CGAL::maximum_area_inscribed_k_gon_2` and
+`CGAL::maximum_perimeter_inscribed_k_gon_2` operate on convex polygons
+only. The example below shows that the largest area triangle (green)
+and the largest perimeter triangle (orange, containing the top point)
+of a point set are different in general.
+
+\image html max_triangle.gif
+
+We further provide an algorithm for computing the maximal area
+inscribed axis parallel rectangle 
+
+Given a set of points in the plane, the class `CGAL::Largest_empty_iso_rectangle_2<T>`
+is a data structure that maintains an iso-rectangle with the largest area among
+all iso-rectangles that are inside a given iso-rectangles, and
+that do not contain any point of the point set.
+
+\image html largestEmptyRect.gif
+
+Inscribed volumes are also frequently applied to extract
+geometric properties of objects. The largest area triangle is for example used in
+heuristics for matching archaeological aerial photographs. Largest
+perimeter triangles are used in scoring cross country soaring flights,
+where the goal is basically to fly as far as possible, but still
+return to the departure airfield. To score simply based on the total
+distance flown is not a good measure, since circling in thermals
+allows to increase it easily.
+
+*/ 
+} /* namespace CGAL */
+

Inscribed_areas/doc/Inscribed_areas/PackageDescription.txt

@@ -0,0 +1,29 @@
+/// \defgroup PkgInscribedAreas Inscribed Areas 
+
+/// \defgroup PkgInscribedAreasConcepts Concepts
+/// \ingroup PkgInscribedAreas
+
+/*!
+\addtogroup PkgInscribedAreas
+\todo check generated documentation
+\PkgDescriptionBegin{Inscribed Areas}
+\PkgPicture{ler-detail.png}
+\PkgAuthor{Michael Hoffmann and Eli Packer}
+\PkgDesc{This package provides algorithms for computing inscribed areas. The algorithms for computing inscribed areas are: the largest inscribed k-gon (area or perimeter) of a convex point set and the largest inscribed iso-rectangle.}
+\PkgSince{1.1}
+\cgalbib{cgal:hp-ia}
+\license{\ref licensesGPL "GPL"}
+\PkgDescriptionEnd
+
+This chapter describes concepts, classes, and functions for
+maximum area and perimeter inscribed \f$ k\f$-gon (2D), extremal inscribed
+\f$ k\f$-gon (2D), largest empty isorectangle (2D).
+
+# Assertions #
+
+The optimization code uses infix `OPTIMISATION` in the assertions,
+e.g. defining the compiler flag
+`CGAL_OPTIMISATION_NO_PRECONDITIONS` switches precondition
+checking off, cf. Section  \ref secchecks.
+*/
+