% +------------------------------------------------------------------------+
% | Reference manual page: AABB_tree.tex
% +------------------------------------------------------------------------+
% | 21.02.2009   Author
% | Package: Package
% |
\RCSdef{\RCSAABBtreeRev}{$Id: header.tex 40270 2007-09-07 15:29:10Z lsaboret $}
\RCSdefDate{\RCSAABBtreeDate}{$Date: 2007-09-07 17:29:10 +0200 (Ven, 07 sep 2007) $}
% |
\ccRefPageBegin
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+


\begin{ccRefClass}{AABB_tree<Traits>}  %% add template arg's if necessary

%% \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}.

\ccInclude{AABB_tree.h}

\ccTypes

\ccTypedef{typedef Traits::FT FT;}
          {Field number type.}
\ccGlue
\ccTypedef{typedef Traits::Point_3 Point;}
          {Type of 3D point.}
\ccGlue
\ccTypedef{typedef Traits::Primitive Primitive;}
          {Type of input primitive.}
\ccGlue
\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.}

%\ccNestedType{AABB}{some nested types}

\ccCreation
\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.}

\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{void clear(void);}
{Clears the AABB tree. }

\ccMethod{Bounding_box root_bbox();}
{Returns the root 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. }

% INTERSECTION TESTS
\ccHeading{Intersection Tests}

\ccMethod{template <class Query>
	        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}.}
	
\ccMethod{template <class Query>
	        size_t number_of_intersections(const Query& query);}
{Returns the number of intersections between the query and the input primitives. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{Traits}.}

\ccMethod{template <class Query, class OutputIterator>
	        OutputIterator 
          all_intersected_primitives(const Query& query,
                                     OutputIterator out);}
{Outputs to the iterator the list of all intersected primitives. This function does not compute the intersection points and is hence faster than the function \ccc{all_intersections} function below. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{Traits}.}

\ccMethod{template <class Query>
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}.}

% INTERSECTIONS
\ccHeading{Intersections}
	
\ccMethod{template <class Query, class OutputIterator>
	        OutputIterator 
          all_intersections(const Query& query,
                            OutputIterator out);}
{Outputs to the iterator the list of all intersections between the query and input data, as objects of type \ccc{Point_and_primitive}. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates and intersections are defined in the \ccc{Traits}.}

\ccMethod{template <class Query>
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}.}


% DISTANCE QUERIES
\ccHeading{Distance Queries}

\ccMethod{Point
closest_point(const Point& query, 
              const Point& hint);} 
{Returns the point on all input primitives which is closest to the query. In case of several closest points one arbitrarily chosen point is returned.  Parameter \ccc{hint} is assumed to be any point located on the input primitives (the closer \ccc{hint} to \ccc{query}, the faster). Parameter \ccc{hint} can be omitted. If the internal KD-tree data structure has been constructed using function \ccc{construct_search_tree} (see below), it is used to efficiently query the nearest hint point from the query. Otherwise a naive hint point is taken as the first primitive reference point. }

\ccMethod{Primitive
closest_primitive(const Point& query, 
                  const Point& hint);} 
{Returns the primitive which realizes the smallest distance between the query point and all input primitives. See \ccc{closest_point} function for the optional \ccc{hint} parameter. }

\ccMethod{Point_and_primitive
closest_point_and_primitive(const Point& query, 
                            const Point& hint);} 
{Returns a \ccc{std::pair<Point,Primitive>} which realizes the smallest distance between the query point and all input primitives. See \ccc{closest_point} function for the optional \ccc{hint} parameter. }

\ccMethod{FT
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 <class ConstPointIterator>
void construct_search_tree(ConstPointIterator begin,
                           ConstPointIterator beyond);}
{ Constructs the internal search KD-tree used to accelerate the distance queries from a specified point set. Each point from the specified point set must be located on the input primitives. For a triangle surface mesh this point set can be provided as the vertex points or as the triangle centroids.}
\end{ccAdvanced}

\ccSeeAlso

\ccc{AABBTraits}, \\
\ccc{AABBPrimitive}.

\end{ccRefClass}

% +------------------------------------------------------------------------+
%%RefPage: end of main body, begin of footer
\ccRefPageEnd
% EOF
% +------------------------------------------------------------------------+