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


\begin{ccRefConcept}{AABBTraits}

%% \ccHtmlCrossLink{}     %% add further rules for cross referencing links
%% \ccHtmlIndexC[concept]{} %% add further index entries

\ccDefinition
  
The concept \ccRefName\ provides the geometric primitive types and methods for the class \ccc{AABB_tree<AT>}.

\ccTypes

\ccNestedType{size_type}{Unsigned integral size type.}

\ccNestedType{FT}{Value type of the \ccc{Squared_distance} functor.}

\ccNestedType{Point_3}{Type of a 3D point.}

\ccNestedType{Primitive}{Type of primitive.
                         Must be a model of the concept \ccc{AABBPrimitive}.}

\ccNestedType{Bounding_box}{Bounding box type.}

\ccTypedef{typedef std::pair<Point_3, Primitive::Id> Point_and_primitive_id;}{}

\ccTypedef{typedef std::pair<Object, Primitive::Id> Object_and_primitive_id;}{}

% NOT NEEDED
%\ccGlue
%\ccNestedType{Sphere}{Sphere type required for distance queries.}

During the construction of the \ccc{AABB_tree}, the primitives are sorted according to some comparison functions related to the $x$, $y$ or $z$ coordinate axis:
%\ccMethod{bool less_x(const Primitive & pr1, const Primitive & pr2);}{}
%\ccGlue
%\ccMethod{bool less_y(const Primitive & pr1, const Primitive & pr2);}{}
%\ccGlue
%\ccMethod{bool less_z(const Primitive & pr1, const Primitive & pr2);}{}

\ccNestedType{Sort_primitives} 
{A functor object to sort primitives along the longest axis of their bounding box. Provides the operator:
\ccc{bool operator()(InputIterator first, InputIterator beyond,const Bounding_box& bbox);} Iterator \ccc{InputIterator} must have \ccc{Primitive} as value type. The operator is used when computing the two children nodes of a node whose bounding box is \ccc{bbox}. It should modify the iterator range in such a way that its first half and its second half correspond to the two children nodes.}

%\ccMethod{Bounding_box compute_bbox();}
%{Returns the bounding box of a set of primitives.}
\ccNestedType{Compute_bbox} 
{A functor object to compute the bounding box of a set of primitives. Provides the operator:
\ccc{Bounding_box operator()(Input_iterator begin,                                              Input_iterator beyond);} Iterator \ccc{InputIterator} must have \ccc{Primitive} as value type. }

The following predicates are required for each type \ccc{Query}
for which the class \ccc{AABB_tree<AT>} may receive an intersection detection or computation query.

%\ccMethod{bool do_intersect(const Query & q, const Bounding_box & box);}
%{Returns \ccc{true} iff the query intersects the bounding box.}
%\ccGlue	
%\ccMethod{bool do_intersect(const Query & q, const Primitive& primitive);}
%{Returns \ccc{true} iff the query intersects the primitive.}
%\ccGlue	
\ccNestedType{Do_intersect} 
{A functor object to compute intersection predicates between the query and the nodes of the tree. Provides the operators:
\ccc{bool operator()(const Query & q, const Bounding_box & box);} which returns \ccc{true} iff the query intersects the bounding box, and \ccc{bool operator()(const Query & q, const Primitive & primitive);} which returns \ccc{true} iff the query intersects the primitive.}

% \ccMethod{int do_transversally_intersect(const Query & q, const Primitive& primitive);}
%{Returns 1 iff the query intersects the primitive transversally, returns 0 iff the query does not intersect the primitive and returns a negative error code in case of a non-transversal intersection.}
%\ccGlue	
%\ccMethod{boost::optional<Object_and_primitive_id> intersection(const Query & q, const Primitive& primitive);}
%{Returns the intersection as a pair composed of an object and a primitive id, iff the query intersects the primitive.}
%\ccGlue	
\ccNestedType{Intersect} 
{A functor object to compute the intersection of a query and a primitive. Provides the operator:
\ccc{boost::optional<Object_and_primitive_id> operator()(const Query & q, const Primitive& primitive);} which returns the intersection as a pair composed of an object and a primitive id, iff the query intersects the primitive.}

The following predicates are required for each type \ccc{Query}
for which the class \ccc{AABB_tree<AT>} may receive a distance query.

%\ccMethod{bool is_closer(const Point & p, const Bounding_box& box, const Point & q);}
%{Returns true, iff the primitive is closer to \ccc{p} than \ccc{q} is.}
%\ccGlue	
%\ccMethod{bool is_closer(const Point & p, const Primitive& primitive, const Point & q);}
%{Returns true, iff the primitive is closer to \ccc{p} than \ccc{q} is.}
%\ccGlue
\ccNestedType{Compare_distance} 
{A functor object to compute distance comparisons between the query and the nodes of the tree. Provides the operators:
\ccc{bool operator()(const Query & query, const Bounding_box& box, const Point & closest);} which returns \ccc{true} iff the bounding box is closer to \ccc{query} than \ccc{closest} is, and \ccc{bool operator()(const Query & query, const Primitive & primitive, const Point & closest);} which returns \ccc{true} iff \ccc{primitive} is closer to the \ccc{query} than \ccc{closest} is.}

%\ccMethod{Point_3 closest_point(const Point_3 & p, const Primitive& primitive, const Point_3 & q);}
%{Returns the closest point to \ccc{p}, among \ccc{q} and all points of the primitive.}
%\ccGlue
\ccNestedType{Closest_point} 
{A functor object to compute closest point from the query on a primitive. Provides the operator:
\ccc{Point_3 operator()(const Query& query, const Primitive& primitive, const Point_3 & closest);} which returns the closest point to \ccc{query}, among \ccc{closest} and all points of the primitive.}

%\ccMethod{FT squared_distance(const Point_3 & p, const Point_3 & q);}
%{Returns the squared distance between \ccc{p} and \ccc{q}.}
\ccNestedType{Squared_distance}
{A functor object to compute the squared distance between the query and a point. Provides the operator:
\ccc{FT operator()(const Query& query, const Point_3 & p);} which returns the squared distance between \ccc{query} and \ccc{p}.}

\ccCreation
\ccCreationVariable{traits}  %% choose variable name

%\ccConstructor{AABBTraits();}{Default constructor.}

\ccOperations

\ccMethod{Sort_primitives sort_primitives_object();}
{Returns the primitive sorting functor.}

\ccMethod{Compute_bbox compute_bbox_object();}
{Returns the bounding box constructor.}

\ccMethod{Do_intersect do_intersect_object();}
{Returns the intersection detection functor.}

\ccMethod{Intersect intersect_object();}
{Returns the intersection constructor.}

\ccMethod{Compare_distance compare_distance_object();}
{Returns the distance comparison functor.}

\ccMethod{Closest_point closest_point_object();}
{Returns the closest point constructor.}


% NOT NEEDED
%\ccMethod{bool is_contained(const Sphere & a, const Sphere & b);}{Returns \ccc{true} iff sphere $a$ is contained in sphere $b$. Both spheres are assumed to share the same center.}

\ccHasModels
\ccc{AABB_traits<GeomTraits,TrianglePrimitive>}.

\ccSeeAlso
\ccc{AABB_traits<GeomTraits,TrianglePrimitive>}\\
\ccc{AABB_tree<AT>}
\ccc{AABBPrimitive}

\end{ccRefConcept}

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

