From a6cf3261543bf92f20165274d6ff562ac7daed73 Mon Sep 17 00:00:00 2001 From: Pierre Alliez Date: Mon, 4 May 2009 20:08:00 +0000 Subject: [PATCH] AABB tree: - examples primitive files in a separate folder - more on doc from second review. --- .gitattributes | 8 ++-- AABB_tree/doc_tex/AABB_tree/api.tex | 4 +- AABB_tree/doc_tex/AABB_tree/details.tex | 4 +- AABB_tree/doc_tex/AABB_tree/examples.tex | 4 ++ AABB_tree/doc_tex/AABB_tree/main.tex | 2 +- AABB_tree/doc_tex/AABB_tree_ref/AABB_tree.tex | 43 +++++++++---------- .../AABB_polyhedron_edge_example.cpp | 2 +- .../AABB_polyhedron_facet_example.cpp | 2 +- .../AABB_tree/AABB_segment_3_example.cpp | 2 +- .../AABB_tree/AABB_triangle_3_example.cpp | 2 +- .../AABB_polyhedron_edge_primitive.h | 0 .../AABB_polyhedron_triangle_primitive.h | 0 .../{ => primitives}/AABB_segment_primitive.h | 0 .../AABB_triangle_primitive.h | 0 14 files changed, 38 insertions(+), 35 deletions(-) rename AABB_tree/include/CGAL/{ => primitives}/AABB_polyhedron_edge_primitive.h (100%) rename AABB_tree/include/CGAL/{ => primitives}/AABB_polyhedron_triangle_primitive.h (100%) rename AABB_tree/include/CGAL/{ => primitives}/AABB_segment_primitive.h (100%) rename AABB_tree/include/CGAL/{ => primitives}/AABB_triangle_primitive.h (100%) diff --git a/.gitattributes b/.gitattributes index c6af722e93c..10506f3a3a2 100644 --- a/.gitattributes +++ b/.gitattributes @@ -27,14 +27,14 @@ AABB_tree/examples/AABB_tree/AABB_triangle_3_example.cpp -text AABB_tree/examples/AABB_tree/CMakeLists.txt -text AABB_tree/examples/AABB_tree/cleanup.bat -text AABB_tree/include/CGAL/AABB_intersections.h -text -AABB_tree/include/CGAL/AABB_polyhedron_edge_primitive.h -text -AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h -text AABB_tree/include/CGAL/AABB_search_tree.h -text -AABB_tree/include/CGAL/AABB_segment_primitive.h -text AABB_tree/include/CGAL/AABB_traits.h -text -AABB_tree/include/CGAL/AABB_triangle_primitive.h -text AABB_tree/include/CGAL/intersections/Triangle_3_line_3_intersection.h -text AABB_tree/include/CGAL/intersections/nearest_point_segment_3.h -text +AABB_tree/include/CGAL/primitives/AABB_polyhedron_edge_primitive.h -text +AABB_tree/include/CGAL/primitives/AABB_polyhedron_triangle_primitive.h -text +AABB_tree/include/CGAL/primitives/AABB_segment_primitive.h -text +AABB_tree/include/CGAL/primitives/AABB_triangle_primitive.h -text AABB_tree/test/AABB_tree/CMakeLists.txt -text AABB_tree/test/AABB_tree/aabb_intersection_triangle_test.cpp -text AABB_tree/test/AABB_tree/aabb_projection_edge_test.cpp -text diff --git a/AABB_tree/doc_tex/AABB_tree/api.tex b/AABB_tree/doc_tex/AABB_tree/api.tex index 1e8d08733ef..ac1dca38dda 100644 --- a/AABB_tree/doc_tex/AABB_tree/api.tex +++ b/AABB_tree/doc_tex/AABB_tree/api.tex @@ -13,7 +13,7 @@ Intersections tests: \item Function \ccc{number_of_intersected_primitives} counts all intersected primitives. %\item Function \ccc{number_of_transversal_intersections} counts all transversal intersections, and returns an error code if some intersections are not transversal. \item Function \ccc{all_intersected_primitives} enumerates all intersected primitives without constructing the corresponding intersection objects. -\item Function \ccc{any_intersected_primitive} returns the first encoutered intersecting primitive (if any) without constructing the corresponding intersection object, and stops at the first encountered intersection. +\item Function \ccc{any_intersected_primitive} returns the first encountered intersecting primitive (if any) without constructing the corresponding intersection object, and stops at the first encountered intersection. \end{itemize} Intersections: @@ -22,6 +22,6 @@ Intersections: \item Function \ccc{any_intersection} detects and constructs the first encountered intersecting primitive and constructs the corresponding object. This function is fast as it stops at the first encountered intersection. \end{itemize} -\paragraph{Distance.} An AABB tree can compute the closest point from a given point query to the input primitives through the function \ccc{closest_point(query,hint)}. In addition, it can compute the closest primitive from a given point query through the functions \ccc{closest_point_and_primitive(query,hint)} and \ccc{closest_primitive(query,hint)}, i.e., the primitive which realizes the minimum distance from the point query. The latter function is a loose version of the primer in the sense that it does not precise which point on this primitive is the closest. This is often sufficient in some applications to know which primitive is closer. +\paragraph{Distance.} An AABB tree can compute the closest point from a given point query to the input primitives through the function \ccc{closest_point(query,hint)}. In addition, it can compute the closest primitive from a given point query through the functions \ccc{closest_point_and_primitive(query,hint)} and \ccc{closest_primitive(query,hint)}, i.e., the primitive which realizes the minimum distance from the point query. The latter function is a loose version of the former in the sense that it does not return which point on this primitive is the closest. This is often sufficient in some applications to know which primitive is closer. The hint parameter, which can be omitted, provides a way to indicate a point already on one of the primitives. Although this hint can be chosen arbitrarily, the closer from the query the faster. \ No newline at end of file diff --git a/AABB_tree/doc_tex/AABB_tree/details.tex b/AABB_tree/doc_tex/AABB_tree/details.tex index 03901dac516..ee5416dc55d 100644 --- a/AABB_tree/doc_tex/AABB_tree/details.tex +++ b/AABB_tree/doc_tex/AABB_tree/details.tex @@ -2,6 +2,6 @@ \section{Implementation Details} \label{AABB_tree_section_details} -The hierarchy construction is initialized by computing the AABB of the whole set of input primitives. All primitives are then stored along the longest axis of this box, and the primitives are separated into two equal sized sets. This procedure is applied recursively until an AABB contains a single primitive. +The hierarchy construction is initialized by computing the AABB of the whole set of input primitives. All primitives are then sorted along the longest axis of this box, and the primitives are separated into two equal sized sets. This procedure is applied recursively until an AABB contains a single primitive. -In practice the design is slightly different than the one described above as the tree is leafless as presented in OPCODE \cite{cgal:t-ocdl-05}. An intersection query traverses the tree by computing intersection tests only with respect to the AABBs during traversal, and with respect to the input primitives at the end of traversal, i.e., in the leafs of the tree. A projection query between, e.g., a point $q$ and a set of triangle primitives is turned into a \emph{ball} query centered at the query point. The ball traverses the tree while recursively querying intersections with the AABBs, and computes the closest point $p$ from the query point to the input primitives when the traversal ends, i.e., at the leafs of the tree. The ball radius is then shrunk to the distance between $p$ and $q$ for all remaining recursive tree traversals. Efficiency is achieved through setting the initial ball radius to a small value albeit guaranteed to intersect the input primitives. \ No newline at end of file +In practice the design is slightly different than the one described above as the tree is leafless as presented in {\sc opcode} \cite{cgal:t-ocdl-05}. An intersection query traverses the tree by computing intersection tests only with respect to the AABBs during traversal, and with respect to the input primitives at the end of traversal, i.e., in the leafs of the tree. A projection query between, e.g., a point $q$ and a set of triangle primitives is turned into a \emph{ball} query centered at the query point. The ball traverses the tree while recursively querying intersections with the AABBs, and computes the closest point $p$ from the query point to the input primitives when the traversal ends, i.e., at the leafs of the tree. The ball radius is then shrunk to the distance between $p$ and $q$ for all remaining recursive tree traversals. Efficiency is achieved through setting the initial ball radius to a small value albeit guaranteed to intersect the input primitives. \ No newline at end of file diff --git a/AABB_tree/doc_tex/AABB_tree/examples.tex b/AABB_tree/doc_tex/AABB_tree/examples.tex index b51f6878e91..39b4e9a36f0 100644 --- a/AABB_tree/doc_tex/AABB_tree/examples.tex +++ b/AABB_tree/doc_tex/AABB_tree/examples.tex @@ -2,14 +2,18 @@ \section{Examples} \label{AABB_tree_section_examples} +\subsection{Triangles in a list} In the following example a set of 3D triangles is stored in a list. The AABB primitive wraps a triangle and an iterator in the list. We computes the number of intersections between a 3D line and the input triangles, and the closest point from a query point to the input triangles. \ccIncludeExampleCode{AABB_tree/AABB_triangle_3_example.cpp} +\subsection{Triangle facets of a polyhedral surface} The following example computes the number of intersections between a 3D ray and a set of facets of a triangle polyhedral surface. The AABB primitive wraps a facet handle and generates on the fly a 3D triangle each time its object function is called. \ccIncludeExampleCode{AABB_tree/AABB_polyhedron_facet_example.cpp} +\subsection{Segments in a list} The following example computes the number of intersections between a 3D plane and a set of 3D segments. The segments are stored into a list, and the AABB primitive wraps a segment and an iterator in the list. \ccIncludeExampleCode{AABB_tree/AABB_segment_3_example.cpp} +\subsection{Edges of a polyhedral surface} The following example computes the number of intersections between a 3D plane and a set of edges of a triangle polyhedral surfaces. The AABB primitive wraps a halfedge handle and generates on the fly a 3D segment each time its object function is called.. \ccIncludeExampleCode{AABB_tree/AABB_polyhedron_edge_example.cpp} diff --git a/AABB_tree/doc_tex/AABB_tree/main.tex b/AABB_tree/doc_tex/AABB_tree/main.tex index d572af2961f..1794a872fd1 100644 --- a/AABB_tree/doc_tex/AABB_tree/main.tex +++ b/AABB_tree/doc_tex/AABB_tree/main.tex @@ -1,7 +1,7 @@ \ccUserChapter{AABB tree\label{AABB_tree}} \label{user_chapter_AABB_tree} -\ccChapterAuthor{Pierre Alliez, Laurent Rineau, Stephane Tayeb, +\ccChapterAuthor{Pierre Alliez, Laurent Rineau, St\'ephane Tayeb, Camille Wormser and Mariette Yvinec} \input{AABB_tree/PkgDescription} diff --git a/AABB_tree/doc_tex/AABB_tree_ref/AABB_tree.tex b/AABB_tree/doc_tex/AABB_tree_ref/AABB_tree.tex index b1978f3bed8..241126a3169 100644 --- a/AABB_tree/doc_tex/AABB_tree_ref/AABB_tree.tex +++ b/AABB_tree/doc_tex/AABB_tree_ref/AABB_tree.tex @@ -12,14 +12,14 @@ % +------------------------------------------------------------------------+ -\begin{ccRefClass}{AABB_tree} %% add template arg's if necessary +\begin{ccRefClass}{AABB_tree} %% \ccHtmlCrossLink{} %% add further rules for cross referencing links %% \ccHtmlIndexC[class]{} %% add further index entries \ccDefinition -The class \ccRefName\ is a static data structure for efficient intersection and distance computations in 3D. It builds a hierarchy of axis-aligned bounding boxes from a set of 3D geometric objects such as triangles, and can receive intersection and distance queries, provided that the corresponding predicates are implemented in the traits class. The template parameter \ccc{Traits} stands for a traits class which must be a model of the concept \ccc{AABBTraits}. +The class \ccRefName\ is a static data structure for efficient intersection and distance computations in 3D. It builds a hierarchy of axis-aligned bounding boxes from a set of 3D geometric objects such as triangles, and can receive intersection and distance queries, provided that the corresponding predicates are implemented in the traits class. The template parameter must be a model of the concept \ccc{AABBTraits}. \ccInclude{AABB_tree.h} @@ -37,8 +37,8 @@ The class \ccRefName\ is a static data structure for efficient intersection and \ccTypedef{typedef Traits::Bounding_box Bounding_box;} {Type of bounding box.} \ccGlue -\ccNestedType{Point_and_primitive} - {A pair composed of a point and a primitive.} +\ccTypedef{typedef std::pair Point_and_primitive;} + {A pair composed of a point and a primitive.} %\ccNestedType{AABB}{some nested types} @@ -46,36 +46,36 @@ The class \ccRefName\ is a static data structure for efficient intersection and \ccCreationVariable{tree} %% variable name \ccConstructor{AABB_tree();}{Default constructor.} -\ccConstructor{template < class ConstPrimitiveIterator> - AABB_tree( ConstPrimitiveIterator begin, - ConstPrimitiveIterator beyond);} -{Builds the datastructure. Type \ccc{ConstPrimitiveIterator} can be any const iterator on a container of \ccc{Primitive::Object} such that \ccc{Primitive} has a constructor taking a \ccc{ConstPrimitiveIterator} as argument.} +\ccConstructor{template < class InputIterator> + AABB_tree( InputIterator begin, + InputIterator beyond);} +{Builds the datastructure. Type \ccc{InputIterator} can be any const iterator on a container of \ccc{Primitive::Datum} such that \ccc{Primitive} has a constructor taking a \ccc{InputIterator} as argument.} \ccOperations -\ccMethod{template < class ConstPrimitiveIterator> - bool clear_and_insert(ConstPrimitiveIterator begin, - ConstPrimitiveIterator beyond);} -{Clears the current tree and rebuilds it from scratch. See constructor above for the parameters. Returns \ccc{true} iff the memory allocation is successful. } +\ccMethod{template < class InputIterator> + bool clear_and_insert(InputIterator begin, + InputIterator beyond);} +{Clears the current tree and rebuilds it from scratch. See constructor above for the parameters. Returns \ccc{true} iff, the memory allocation is successful. } -\ccMethod{void clear(void);} +\ccMethod{void clear();} {Clears the AABB tree. } -\ccMethod{Bounding_box root_bbox();} +\ccMethod{Bounding_box bbox();} {Returns the axis-aligned bounding box of the whole tree. } \ccMethod{size_t size();} {Returns the number of primitives in the tree. } \ccMethod{bool empty();} -{Returns \ccc{true} iff tree contains no primitive. } +{Returns \ccc{true} iff, tree contains no primitive. } % INTERSECTION TESTS \ccHeading{Intersection Tests} \ccMethod{template bool do_intersect(const Query& query);} -{ Returns \ccc{true} iff the query intersects the input primitives. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{Traits}.} +{ Returns \ccc{true} iff, the query intersects the input primitives. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{Traits}.} \ccMethod{template size_t number_of_intersected_primitives(const Query& query);} @@ -92,7 +92,7 @@ The class \ccRefName\ is a static data structure for efficient intersection and \ccMethod{template bool any_intersected_primitive(const Query& query, Primitive& primitive);} -{Return \ccc{true} iff the query intersects at least one of the input primitives. In the positive, saves the first encountered primitive to the second parameter. Type \ccc{Query} must be a type for which \ccc{do_intersect} and intersection predicates are defined in the \ccc{Traits}.} +{Return \ccc{true} iff, the query intersects at least one of the input primitives. In the positive, saves the first encountered primitive to the second parameter. Type \ccc{Query} must be a type for which \ccc{do_intersect} and intersection predicates are defined in the \ccc{Traits}.} % INTERSECTIONS \ccHeading{Intersections} @@ -106,7 +106,7 @@ bool any_intersected_primitive(const Query& query, \ccMethod{template bool any_intersection(const Query& query, Point_and_primitive& point_and_primitive);} -{Returns \ccc{true} iff the query intersects at least one of the input primitives. In the positive, saves the first encountered intersection to the second parameter. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates and intersections are defined in the \ccc{Traits}.} +{Returns \ccc{true} iff, the query intersects at least one of the input primitives. In the positive, saves the first encountered intersection to the second parameter. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates and intersections are defined in the \ccc{Traits}.} % DISTANCE QUERIES @@ -132,16 +132,15 @@ squared_distance(const Point& query, const Point& hint);} {Returns the minimum squared distance between the query point and all input primitives. See \ccc{closest_point} function for the optional \ccc{hint} parameter. } - \ccHeading{Accelerating the distance queries} \ccMethod{void construct_search_tree();} { Constructs the internal search KD-tree used to accelerate the distance queries. The points in the search tree are taken from the primitives by calling the member function \ccc{point_on} from the primitive.} \begin{ccAdvanced} -\ccMethod{template -void construct_search_tree(ConstPointAndPrimitiveIterator begin, - ConstPointAndPrimitiveIterator beyond);} +\ccMethod{template +void construct_search_tree(InputIterator begin, + InputIterator beyond);} { Constructs the internal search KD-tree used to accelerate the distance queries from a specified point set. Each point from the specified \ccc{Point_and_primitive} set should be located on the corresponding input primitive. For a triangle surface mesh this point set can be provided as the vertex points or as the triangle centroids.} \end{ccAdvanced} diff --git a/AABB_tree/examples/AABB_tree/AABB_polyhedron_edge_example.cpp b/AABB_tree/examples/AABB_tree/AABB_polyhedron_edge_example.cpp index 5013ad3f23d..fbcb58a35a9 100644 --- a/AABB_tree/examples/AABB_tree/AABB_polyhedron_edge_example.cpp +++ b/AABB_tree/examples/AABB_tree/AABB_polyhedron_edge_example.cpp @@ -27,7 +27,7 @@ #include #include #include -#include +#include #include diff --git a/AABB_tree/examples/AABB_tree/AABB_polyhedron_facet_example.cpp b/AABB_tree/examples/AABB_tree/AABB_polyhedron_facet_example.cpp index 661edb2a960..00a4fb663bf 100644 --- a/AABB_tree/examples/AABB_tree/AABB_polyhedron_facet_example.cpp +++ b/AABB_tree/examples/AABB_tree/AABB_polyhedron_facet_example.cpp @@ -27,7 +27,7 @@ #include #include #include -#include +#include #include diff --git a/AABB_tree/examples/AABB_tree/AABB_segment_3_example.cpp b/AABB_tree/examples/AABB_tree/AABB_segment_3_example.cpp index 54b46504bd2..18d0ee2e2fe 100644 --- a/AABB_tree/examples/AABB_tree/AABB_segment_3_example.cpp +++ b/AABB_tree/examples/AABB_tree/AABB_segment_3_example.cpp @@ -27,7 +27,7 @@ #include #include -#include +#include #include diff --git a/AABB_tree/examples/AABB_tree/AABB_triangle_3_example.cpp b/AABB_tree/examples/AABB_tree/AABB_triangle_3_example.cpp index 186e184ee01..79cbf94ec86 100644 --- a/AABB_tree/examples/AABB_tree/AABB_triangle_3_example.cpp +++ b/AABB_tree/examples/AABB_tree/AABB_triangle_3_example.cpp @@ -27,7 +27,7 @@ #include #include -#include +#include #include diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_edge_primitive.h b/AABB_tree/include/CGAL/primitives/AABB_polyhedron_edge_primitive.h similarity index 100% rename from AABB_tree/include/CGAL/AABB_polyhedron_edge_primitive.h rename to AABB_tree/include/CGAL/primitives/AABB_polyhedron_edge_primitive.h diff --git a/AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h b/AABB_tree/include/CGAL/primitives/AABB_polyhedron_triangle_primitive.h similarity index 100% rename from AABB_tree/include/CGAL/AABB_polyhedron_triangle_primitive.h rename to AABB_tree/include/CGAL/primitives/AABB_polyhedron_triangle_primitive.h diff --git a/AABB_tree/include/CGAL/AABB_segment_primitive.h b/AABB_tree/include/CGAL/primitives/AABB_segment_primitive.h similarity index 100% rename from AABB_tree/include/CGAL/AABB_segment_primitive.h rename to AABB_tree/include/CGAL/primitives/AABB_segment_primitive.h diff --git a/AABB_tree/include/CGAL/AABB_triangle_primitive.h b/AABB_tree/include/CGAL/primitives/AABB_triangle_primitive.h similarity index 100% rename from AABB_tree/include/CGAL/AABB_triangle_primitive.h rename to AABB_tree/include/CGAL/primitives/AABB_triangle_primitive.h