mirror of https://github.com/CGAL/cgal
164 lines
10 KiB
TeX
164 lines
10 KiB
TeX
% +------------------------------------------------------------------------+
|
||
% | 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<AT>} %% 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 \ccc{AT}. The template parameter \ccc{AT} stands for a traits class which must be a model of the concept \ccc{AABBTraits}.
|
||
|
||
\ccInclude{CGAL/AABB_tree.h}
|
||
|
||
\ccTypes
|
||
|
||
\ccTypedef{typedef AT::Size_type Size_type;}
|
||
{Unsigned integral size type.}
|
||
\ccGlue
|
||
\ccTypedef{typedef AT::FT FT;}
|
||
{Number type returned by the distance queries.}
|
||
\ccGlue
|
||
\ccTypedef{typedef AT::Point_3 Point;}
|
||
{Type of 3D point.}
|
||
\ccGlue
|
||
\ccTypedef{typedef AT::Primitive Primitive;}
|
||
{Type of input primitive.}
|
||
\ccGlue
|
||
\ccTypedef{typedef AT::Bounding_box Bounding_box;}
|
||
{Type of bounding box.}
|
||
\ccGlue
|
||
\ccTypedef{typedef std::pair<Point, Primitive::Id> Point_and_primitive_id;}
|
||
{}
|
||
\ccGlue
|
||
\ccTypedef{typedef std::pair<CGAL::Object, Primitive::Id> Object_and_primitive_id;}
|
||
{}
|
||
|
||
%\ccNestedType{}{some nested types}
|
||
|
||
\ccCreation
|
||
\ccCreationVariable{tree} %% variable name
|
||
|
||
\ccConstructor{AABB_tree();}{Constructs an empty tree.}
|
||
\ccConstructor{template < class InputIterator>
|
||
AABB_tree( InputIterator begin,
|
||
InputIterator beyond);}
|
||
{Builds the AABB tree data structure. Type \ccc{InputIterator} can be any const iterator such that \ccc{Primitive} has a constructor taking a \ccc{InputIterator} as argument. The tree stays empty if the memory allocation is not successful.}
|
||
|
||
\ccOperations
|
||
|
||
\ccMethod{template < class InputIterator>
|
||
bool rebuild(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();}
|
||
{Clears the AABB tree. }
|
||
|
||
\ccMethod{Bounding_box bbox();}
|
||
{Returns the axis-aligned bounding box of the whole tree. }
|
||
|
||
\ccMethod{Size_type 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 at least one of the input primitives. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{AT} class.}
|
||
|
||
\ccMethod{template <class Query>
|
||
Size_type number_of_intersected_primitives(const Query& query);}
|
||
{Returns the number of primitives intersected by the query. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{AT} class.}
|
||
|
||
%\ccMethod{template <class Query> size_type number_of_transversal_intersections(const Query& query);} {Returns the number of primitives intersected transversally by the query, if all intersections are transversal. Type \ccc{Query} must be a type for which \ccc{do_transversally_intersect} predicates are defined in the \ccc{AT} class. If any of the intersections is not transversal, the method returns the error code (a negative integer) returned by \ccc{do_transversally_intersect} at the first non-transversal intersection encountered.}
|
||
|
||
\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 ids. 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{AT} class.}
|
||
|
||
\ccMethod{template <class Query>
|
||
boost::optional<Primitive::Id>
|
||
any_intersected_primitive(const Query& query);}
|
||
{Returns the first encountered intersected primitive id, iff the query intersects at least one of the input primitives. No particular order is guaranteed over the tree traversal, such that, e.g, the primitive returned is not necessarily the closest from the source point of a ray query. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates are defined in the \ccc{AT} class.}
|
||
|
||
|
||
% 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{Object_and_primitive_id}. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates and intersections are defined in the \ccc{AT} class.}
|
||
|
||
\ccMethod{template <class Query>
|
||
boost::optional<Object_and_primitive_id>
|
||
any_intersection(const Query& query);}
|
||
{Returns the first encountered intersection, iff the query intersects at least one of the input primitives. No particular order is guaranteed over the tree traversal, such that, e.g, the primitive returned is not necessarily the closest from the source point of a ray query. Type \ccc{Query} must be a type for which \ccc{do_intersect} predicates and intersections are defined in the \ccc{AT} class.}
|
||
|
||
|
||
|
||
% DISTANCE QUERIES
|
||
\ccHeading{Distance queries}
|
||
|
||
\ccMethod{FT
|
||
squared_distance(const Point& query,
|
||
const Point& hint);}
|
||
{Returns the minimum squared distance between the query point and all input primitives. Parameter \ccc{hint} is assumed to be any point located on the input primitives (the closer \ccc{hint} to \ccc{query}, the faster). If \ccc{hint} is closer to \ccc{query} than any of the primitives, \ccc{hint} is returned. Parameter \ccc{hint} can be omitted. When omitted, and if the internal KD-tree data structure has been constructed using function \ccc{accelerate_distance_queries} (see below), the latter is used to efficiently query the nearest hint point from the query, among a set of hint points stored in the internal KD-tree. Otherwise, the first primitive reference point is taken as a naive hint point. }
|
||
|
||
\ccMethod{Point
|
||
closest_point(const Point& query,
|
||
const Point& hint);}
|
||
{Returns the point in the union of all input primitives which is closest to the query. In case there are several closest points, one arbitrarily chosen closest point is returned. <20>Parameter \ccc{hint} is assumed to be any point located on the input primitives (the closer \ccc{hint} to \ccc{query}, the faster). If \ccc{hint} is closer to \ccc{query} than any of the primitives, \ccc{hint} is returned. Parameter \ccc{hint} can be omitted. If the internal KD-tree data structure has been constructed using function \ccc{accelerate_distance_queries} (see below), it is used to efficiently query the nearest hint point from the query, among a set of hint points stored in the internal KD-tree. Otherwise, the first primitive reference point is chosen as a naive hint point.}
|
||
|
||
\ccMethod{Point_and_primitive_id
|
||
closest_point_and_primitive(const Point& query,
|
||
const Point_and_primitive_id& hint);}
|
||
{Returns a \ccc{Point_and_primitive_id} which realizes the smallest distance between the query point and all input primitives. Parameter \ccc{hint} is assumed to be any point and the corresponding input primitive it lies on (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{accelerate_distance_queries} (see below), it is used to efficiently query the nearest hint from the query, among a set of hints stored in the internal KD-tree. Otherwise, the first point and primitive pair is chosen as a naive hint.}
|
||
|
||
|
||
\ccHeading{Accelerating the distance queries}
|
||
|
||
\ccMethod{bool accelerate_distance_queries();}
|
||
{ 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{reference_point} of the primitive. Returns \ccc{true}, iff the memory allocation is successful.}
|
||
|
||
\begin{ccAdvanced}
|
||
\ccMethod{template <class InputIterator>
|
||
bool accelerate_distance_queries(InputIterator begin,
|
||
InputIterator beyond);}
|
||
{ Constructs the internal search KD-tree used to accelerate the distance queries from a specified point set. Iterator \ccc{InputIterator} must have \ccc{Point_and_primitive_id} as value type. Each point from the specified \ccc{Point_and_primitive_id} set must be located on the corresponding input primitive. For a triangle surface mesh this point set can be provided, e.g., as the vertices of the mesh or as the triangle centroids. It is not required to provide one point per primitive, such that, e.g., large input primitive can be sampled with several sample points or, conversely, such that a single point is provided for clusters of small input primitives. Returns \ccc{true}, iff the memory allocation is successful.}
|
||
\end{ccAdvanced}
|
||
|
||
\ccSeeAlso
|
||
|
||
\ccc{AABBTraits}, \\
|
||
\ccc{AABBPrimitive}.
|
||
|
||
\end{ccRefClass}
|
||
|
||
% +------------------------------------------------------------------------+
|
||
%%RefPage: end of main body, begin of footer
|
||
\ccRefPageEnd
|
||
% EOF
|
||
% +------------------------------------------------------------------------+
|
||
|