% +------------------------------------------------------------------------+
% | 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 detection and projection 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 projection 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::Primitive Primitive;}{Type of input primitives.}
\ccGlue
\ccTypedef{typedef Traits::Intersection Intersection;}{Type of intersection result.}
\ccGlue
\ccTypedef{typedef Traits::Projection_query Projection_query;}{Type of projection query.}
\ccGlue
\ccTypedef{typedef Traits::Projection Projection;}{Type of projection point result.}
%\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,
                  const bool construct_search_tree = false);}
{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. Flag \ccc{construct_search_tree} indicates if the search KD-tree used to accelerate the projection queries must be computed during the construction of the AABB tree. In the negative each projection query called without any hint takes the first primitive reference point as hint and is hence slower (the flag is a mean to trade efficiency for memory). }

\ccOperations

\ccMethod{void construct_search_tree();}
{ Constructs the internal search KD-tree used to accelerate the projection queries. The points in the search tree are taken from the primitives by calling the function \ccc{point_on} from the primitive.}

\ccMethod{template <class ConstPointIterator>
void construct_search_tree(ConstPointIterator begin,
                           ConstPointIterator beyond);}
{ Constructs the internal search KD-tree used to accelerate the projection queries from a specified point set. }

% intersection tests

\ccMethod{ template <class Query>
	  bool do_intersect(const Query & q);}
{ Returns \ccc{true} iff the query intersects the primitives. Type \ccc{Query} has to be a type for which \ccc{do_intersect} predicates have been defined in \ccc{Traits}.}
	
\ccMethod{template <class Query>
	  size_t number_of_intersections(const Query& q );}
{Returns the number of primitives intersected by the query. Type \ccc{Query} has to be a type for which \ccc{do_intersect} predicates have been defined in \ccc{Traits}.}
	
\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. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates have been defined in \ccc{Traits}. The value type of OutputIterator is assumed to be \ccc{Intersection}.}

\ccMethod{template <class Query>
bool any_intersection(const Query& query,
                      Intersection& intersection);}
{Returns \ccc{true} iff the query intersects the primitives. In the positive, saves the first encountered intersection to the second parameter. Type \ccc{Query} has to be a type for which \ccc{do_intersect} and intersection predicates have been defined in \ccc{Traits}.}

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

	
\ccMethod{template <class Query, class OutputIterator>
bool any_intersected_primitive(const Query& query,
                               Primitive& primitive);}
{Return \ccc{true} iff the query intersects the primitive. In the positive, saves the first encountered primitive to the second parameter. Type \ccc{Query} has to be a type for which \ccc{do_intersect} and intersection predicates have been defined in \ccc{Traits}.}


% pierre: to be fully generic Projection could be anything	
\ccMethod{Projection 
closest_point(const Projection_query & query, 
              const Projection & hint);} 
{Returns the point on all input primitives which is closest to the query \ccc{q}. Parameter \ccc{hint} is assumed to be any point located on the input primitives (the closer \ccc{hint} to \ccc{q}, the faster the query). Parameter \ccc{hint} can be omitted. If the internal KD-tree data structure has been constructed 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. }

\ccSeeAlso

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

\end{ccRefClass}

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

