First round of Reference Manual revisions

Author: Hippocrates

Documentation/BaseDoxyfile.in

@@ -1396,7 +1396,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
 # generate Latex output.
 
-GENERATE_LATEX         = NO
+GENERATE_LATEX         = YES 
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be

Documentation/pkglist_filter.py

@@ -17,9 +17,9 @@ def main(argv):
             if(index > 0):
                 top_level = pkg[:index]
                 lower_level = pkg[index+1:]
-                filename="/cygdrive/c/Users/stephen/Documents/Programming/CGALDev/Documentation/" + top_level + "/doc/" + lower_level + "/PackageDescription.txt"
+                filename="./" + top_level + "/doc/" + lower_level + "/PackageDescription.txt"
             else:
-                filename="/cygdrive/c/Users/stephen/Documents/Programming/CGALDev/Documentation/" + pkg + "/doc/" + pkg + "/PackageDescription.txt"
+                filename="./" + pkg + "/doc/" + pkg + "/PackageDescription.txt"
             pkgdesc = codecs.open(filename, 'r', encoding='utf-8')
             do_print=False
             for l in pkgdesc:

Polyhedron/demo/Polyhedron/Scene_polyhedron_shortest_path_item.cpp

@@ -256,7 +256,8 @@ void Scene_polyhedron_shortest_path_item::get_as_edge_point(Scene_polyhedron_sho
     }
   }
 
-  inOutLocation.second = Barycentric_coordinate(coords[0], coords[1], coords[2]);
+  Construct_barycentric_coordinate construct_barycentric_coordinate;
+  inOutLocation.second = construct_barycentric_coordinate(coords[0], coords[1], coords[2]);
 }
 
 void Scene_polyhedron_shortest_path_item::get_as_vertex_point(Scene_polyhedron_shortest_path_item::Face_location& inOutLocation)
@@ -276,7 +277,8 @@ void Scene_polyhedron_shortest_path_item::get_as_vertex_point(Scene_polyhedron_s
   FT coords[3] = { FT(0.0), FT(0.0), FT(0.0), };
   coords[maxIndex] = FT(1.0);
 
-  inOutLocation.second = Barycentric_coordinate(coords[0], coords[1], coords[2]);
+  Construct_barycentric_coordinate construct_barycentric_coordinate;
+  inOutLocation.second = construct_barycentric_coordinate(coords[0], coords[1], coords[2]);
 }
 
 bool Scene_polyhedron_shortest_path_item::run_point_select(const Ray_3& ray)
@@ -426,13 +428,15 @@ bool Scene_polyhedron_shortest_path_item::deferred_load(Scene_polyhedron_item* p
   std::string line;
   std::size_t faceId;
   Barycentric_coordinate location;
+  Construct_barycentric_coordinate construct_barycentric_coordinate;
 
   while (std::getline(inFile, line))
   {
     std::istringstream lineStream(line);
     FT coords[3];
     lineStream >> faceId >> coords[0] >> coords[1] >> coords[2];
-    location = Barycentric_coordinate(coords[0], coords[1], coords[2]);
+    
+    location = construct_barycentric_coordinate(coords[0], coords[1], coords[2]);
 
     // std::cout << "Read in face: " << faceId << " , " << location << std::endl;
 

Polyhedron/demo/Polyhedron/Scene_polyhedron_shortest_path_item.h

@@ -40,24 +40,22 @@ class SCENE_POLYHEDRON_SHORTEST_PATH_ITEM_EXPORT Scene_polyhedron_shortest_path_
 
 public:
   typedef Scene_interface::Bbox Bbox;
-
-  typedef boost::property_map<Polyhedron, boost::vertex_index_t>::type VertexIndexMap;
-  typedef boost::property_map<Polyhedron, CGAL::halfedge_index_t>::type HalfedgeIndexMap;
-  typedef boost::property_map<Polyhedron, CGAL::face_index_t>::type FaceIndexMap;
+  
   typedef boost::property_map<Polyhedron, CGAL::vertex_point_t>::type VertexPointMap;
 
   typedef boost::graph_traits<Polyhedron> GraphTraits;
   typedef GraphTraits::face_descriptor face_descriptor;
   typedef GraphTraits::face_iterator face_iterator;
 
   typedef CGAL::Polyhedron_shortest_path_default_traits<Kernel, Polyhedron> Polyhedron_shortest_path_traits;
-  typedef CGAL::Polyhedron_shortest_path<Polyhedron_shortest_path_traits, VertexIndexMap, HalfedgeIndexMap, FaceIndexMap, VertexPointMap> Polyhedron_shortest_path;
+  typedef CGAL::Polyhedron_shortest_path<Polyhedron_shortest_path_traits> Polyhedron_shortest_path;
   typedef Polyhedron_shortest_path::Face_location Face_location;
   typedef CGAL::AABB_face_graph_triangle_primitive<Polyhedron, VertexPointMap> AABB_face_graph_primitive;
   typedef CGAL::AABB_traits<Kernel, AABB_face_graph_primitive> AABB_face_graph_traits;
   typedef CGAL::AABB_tree<AABB_face_graph_traits> AABB_face_graph_tree;
 
   typedef Polyhedron_shortest_path_traits::Barycentric_coordinate Barycentric_coordinate;
+  typedef Polyhedron_shortest_path_traits::Construct_barycentric_coordinate Construct_barycentric_coordinate;
   typedef Polyhedron_shortest_path_traits::Ray_3 Ray_3;
   typedef Polyhedron_shortest_path_traits::Point_3 Point_3;
   typedef Polyhedron_shortest_path_traits::FT FT;

Polyhedron_shortest_path/benchmark/Polyhedron_shortest_path/benchmark_shortest_paths.cpp

@@ -11,6 +11,7 @@
 #include <CGAL/Exact_predicates_inexact_constructions_kernel.h>
 
 #include <CGAL/Polyhedron_3.h>
+#include <CGAL/Polyhedron_items_with_id_3.h>
 #include <CGAL/IO/Polyhedron_iostream.h>
 
 #include <CGAL/Polyhedron_shortest_path/Polyhedron_shortest_path_traits.h>
@@ -29,9 +30,10 @@
 #define UNUSED(X) (void)sizeof(X)
 
 typedef CGAL::Exact_predicates_inexact_constructions_kernel Kernel;
-typedef CGAL::Polyhedron_3<Kernel> Polyhedron_3;
+typedef CGAL::Polyhedron_3<Kernel, CGAL::Polyhedron_items_with_id_3> Polyhedron_3;
 typedef CGAL::Polyhedron_shortest_path_default_traits<Kernel, Polyhedron_3> Traits;
 typedef Traits::Barycentric_coordinate Barycentric_coordinate;
+typedef Traits::Construct_barycentric_coordinate Construct_barycentric_coordinate;
 typedef CGAL::Polyhedron_shortest_path<Traits> Polyhedron_shortest_path;
 typedef boost::graph_traits<Polyhedron_3> GraphTraits;
 typedef GraphTraits::vertex_descriptor vertex_descriptor;
@@ -156,9 +158,10 @@ void print_results(std::ostream& stream, const std::string& filename, const Benc
 
 Barycentric_coordinate random_coordinate(CGAL::Random& rand)
 {
+  Construct_barycentric_coordinate construct_barycentric_coordinate;
   Traits::FT u = rand.uniform_01<Traits::FT>();
   Traits::FT v = rand.uniform_real(Traits::FT(0.0), Traits::FT(1.0) - u);
-  return Barycentric_coordinate(u, v, Traits::FT(1.0) - u - v);
+  return construct_barycentric_coordinate(u, v, Traits::FT(1.0) - u - v);
 }
 
 void run_benchmarks_no_id(CGAL::Random& rand, size_t numTrials, size_t numSources, size_t numQueries, Polyhedron_3& polyhedron, Benchmark_data& outData)

Polyhedron_shortest_path/doc/Polyhedron_shortest_path/Concepts/PolyhedronShortestPathTraits.h

@@ -154,7 +154,7 @@ class PolyhedronShortestPathTraits
   Function object type.
   Must support the result_of protocol, that is the return type of the operator()(A, B) is CGAL::cpp11::result<Intersect_2(A,B)>.
   Must provide
-  `CGAL::cpp11::result<Intersect_2(A,B)> operator()(A obj1, B obj2)`
+  `CGAL::cpp11::result_of<Intersect_2(A,B)> operator()(A obj1, B obj2)`
   to compute the intersection between obj1 and obj2, where A and B can be any one of
   Line_2,
   Ray_2,
@@ -219,21 +219,21 @@ class PolyhedronShortestPathTraits
   /*!
   Function object type that provides 
   `FT operator()(Point_3 p1, Point_3 p2)`
-  to compute the squared distance between p1 and p2.
+  to compute the squared distance between `p1` and `p2`.
   */
   typedef unspecified_type Compute_squared_distance_3;
 
   /*!
   Function object type that provides 
   `Triangle_2 operator()(Triangle_3 t)`
-  which computes a 2-dimensional projection of t
+  which computes a 2-dimensional projection of `t`
   that preserves all edge lengths.
   */
   typedef unspecified_type Project_triangle_3_to_triangle_2;
 
   /*!
   Function object type that provides 
-  `Triangle_2 operator()(Triangle_3 t, size_t i, Segment_2 base)`
+  `Triangle_2 operator()(Triangle_3 t, std::size_t i, Segment_2 base)`
   which computes a 2-dimensional projection of t
   that preserves all edge lengths, such that the `i`th edge of t 
   lies along `base`.
@@ -245,8 +245,8 @@ class PolyhedronShortestPathTraits
   /*! 
   Function object type that provides 
   `FT operator()(Point_2 x0, Point_2 x1, Point_2 p)`
-  which computes the parametric distance of p along the 
-  segment [x0,x1].  That is, it computes `t`, such that
+  which computes the parametric distance of `p` along the 
+  segment `[x0,x1]`.  That is, it computes `t`, such that
   `p = (1.0 - t)*x0 + t*x1`
   
   \pre p is a point along the segment [x0,x1]
@@ -262,22 +262,22 @@ class PolyhedronShortestPathTraits
 
   /*!
   Function object type that provides 
-  `FT operator(Barycentric_coordinate b, size_t i)`
-  to get the ith weight of barycentric coordinate `b`.
+  `FT operator(Barycentric_coordinate b, std::size_t i)`
+  to get the `i`th weight of barycentric coordinate `b`.
   */
   typedef unspecified_type Construct_barycentric_coordinate_weight;
 
   /*!
   Function object type that provides 
   `Barycentric_coordinate operator()(Triangle_2 t, Point_2 p)`
-  which computes the Barycentric location of p in t.
+  which computes the Barycentric location of `p` in `t`.
   */
   typedef unspecified_type Construct_barycentric_coordinate_in_triangle_2;
 
   /*!
   Function object type that provides 
   `Barycentric_coordinate operator()(Triangle_3 t, Point_3 p)`
-  which computes the Barycentric location of p in t.
+  which computes the Barycentric location of `p` in `t`.
   */
   typedef unspecified_type Construct_barycentric_coordinate_in_triangle_3;
 
@@ -288,16 +288,16 @@ class PolyhedronShortestPathTraits
 
   /*!
   Function object type that provides 
-  `std::pair<CGAL::internal::Barycentric_coordinate_type,size_t> operator()(Barycentric_coordinate b)`,
-  which computes the classification and nearest edge of the coordinate `b`
+  `std::pair<CGAL::Polyhedron_shortest_paths_3::Barycentric_coordinate_type,std::size_t> operator()(Barycentric_coordinate b)`,
+  which computes the classification and the associated edge (if applicable) of the coordinate `b`
   \details Returns the pair (`type`, `i`), such that `type` is:
-  - `CGAL::internal::BARYCENTRIC_COORDINATE_VERTEX` if `b` has exactly one non-zero component equal to 1, and the rest are zero
-  - `CGAL::internal::BARYCENTRIC_COORDINATE_EDGE` if `b` has exactly one zero component, and the rest sum to 1
-  - `CGAL::internal::BARYCENTRIC_COORDINATE_INTERNAL` if `b` has no non-zero component, and they all sum to 1
-  - `CGAL::internal::BARYCENTRIC_COORDINATE_EXTERNAL` if the components of `b` do not sum to 1
-  - `CGAL::internal::BARYCENTRIC_COORDINATE_INVALID` otherwise
-  If `type` is `CGAL::internal::BARYCENTRIC_COORDINATE_VERTEX`, `i` should be the index of that vertex
-  If `type` is `CGAL::internal::BARYCENTRIC_COORDINATE_EDGE`, `i` should be the index of the non-zero edge
+  - `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_VERTEX` if `b` has exactly one non-zero component equal to 1, and the rest are zero
+  - `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_EDGE` if `b` has exactly one zero component, and the rest sum to 1
+  - `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_INTERNAL` if `b` has no non-zero component, and they all sum to 1
+  - `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_EXTERNAL` if the components of `b` do not sum to 1
+  - `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_INVALID` otherwise
+  If `type` is `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_VERTEX`, `i` should be the index of that vertex
+  If `type` is `CGAL::Polyhedron_shortest_paths_3::BARYCENTRIC_COORDINATE_EDGE`, `i` should be the index of the non-zero edge
   - 0 if (0,1) are the non-zero coordinates
   - 1 if (1,2) are the non-zero coordinates
   - 2 if (2,0) are the non-zero coordinates
@@ -327,17 +327,17 @@ class PolyhedronShortestPathTraits
   start point of s1, scaled by the length of s1, to the distance of the intersection 
   of s2 with l2 from the start point of s2, scaled by the length of s2.
   
-  \pre the intersection of s1 and l1 is a single point
-  \pre the intersection of s2 and l2 is a single point
+  \pre the intersection of `s1` and `l1` is a single point
+  \pre the intersection of `s2` and `l2` is a single point
   */
   typedef unspecified_type Compare_relative_intersection_along_segment_2;
 
   /*!
   Function object type that provides 
   `template <class VertexPointMap> bool operator()(boost::graph_traits<FaceGraph>::vertex_descriptor v, FaceGraph& p, VertexPointMap vpm)`
   that returns true if the vertex is a saddle vertex (more than 2pi surface area 
-  over all adjacent faces), and false otherwise.  vmp must be a a model of concept ReadablePropertyMap that maps from vertex_descriptor to
-  Point_3 objects.
+  over all adjacent faces), and false otherwise.  `vpm` must be a a model of concept `ReadablePropertyMap` that maps from `vertex_descriptor` to
+  `Point_3` objects.
   */
   typedef unspecified_type Is_saddle_vertex;
 

Polyhedron_shortest_path/doc/Polyhedron_shortest_path/Doxyfile.in

@@ -2,3 +2,8 @@
 PROJECT_NAME = "CGAL ${CGAL_CREATED_VERSION_NUM} - Shortest Paths on Polyhedra"
 INPUT        = ${CMAKE_SOURCE_DIR}/Polyhedron_shortest_path/doc/Polyhedron_shortest_path/ \
                ${CMAKE_SOURCE_DIR}/Polyhedron_shortest_path/include
+
+INTERNAL_DOCS = NO
+EXTRACT_ALL = NO
+HIDE_UNDOC_CLASSES = YES
+HIDE_UNDOC_MEMBERS = YES

Polyhedron_shortest_path/doc/Polyhedron_shortest_path/PackageDescription.txt

@@ -21,6 +21,9 @@
 \cgalPkgSummaryEnd
 
 \cgalPkgShortInfoBegin
+
+\cgalPkgLicense{\ref licensesLGPL "LGPL"}
+\cgalPkgDependsOn{\ref PkgBGLSummary}
 \cgalPkgDemo{Operations on Polyhedra,polyhedron_3.zip}
 \cgalPkgShortInfoEnd
 
@@ -45,6 +48,14 @@
 
 ## Enums ##
 
-- `CGAL::PolyhedronShortestPath::Barycentric_coordinate_type`
+- `CGAL::Polyhedron_shortest_paths_3::Barycentric_coordinate_type`
 
 */
+
+
+/*!
+ \namespace CGAL::Polyhedron_shortest_paths_3
+ 
+ \brief Namespace containing support members specific to this package.
+ */
+

Polyhedron_shortest_path/doc/Polyhedron_shortest_path/Polyhedron_shortest_path.txt

@@ -50,7 +50,7 @@ The algorithm used is based on a paper by Xin and Wang \cgalCite{XinWang2009impr
   \cgalFigureEnd
 
 \subsection Polyhedron_shortest_pathSaddleVertex Saddle Vertices
-  A <em>saddle vertex</em> on a polyhedron is a vertex \f$v\f$ where the sum surface angle of all faces incident at \f$v\f$ is greater than \f$2 \pi\f$, or, in simpler terms, one cannot flatten all the faces incident to \f$v\f$ into the plane without overlap.  Identifying and dealing with saddle vertices are important shortest path algorithms, because they form `blind spots' which cannot be reached by a single geodesic curve.
+  A <em>saddle vertex</em> on a polyhedron is a vertex \f$v\f$ where the sum surface angle of all faces incident at \f$v\f$ is greater than \f$2 \pi\f$, or, in simpler terms, one cannot flatten all the faces incident to \f$v\f$ into the plane without overlap.  Identifying and dealing with saddle vertices are important shortest path algorithms, because they form <em>blind spots</em> which cannot be reached by a single geodesic curve.
 
   \cgalFigureBegin{Saddle_vertex,saddleVertex.png}
   A visibility window (shaded blue) encounters a saddle vertex; the shaded red region behind the vertex is not reachable with a geodesic from the origin point (assuming the geodesic must stay inside the initial window).

Polyhedron_shortest_path/doc/Polyhedron_shortest_path/dependencies

@@ -4,3 +4,5 @@ STL_Extension
 Algebraic_foundations
 Circulator
 Stream_support
+BGL
+AABB_tree