mirror of https://github.com/CGAL/cgal
161 lines
8.9 KiB
TeX
161 lines
8.9 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{AABB_tree.h}
|
|
|
|
\ccTypes
|
|
|
|
\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> 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();}{Constructs an empty tree.}
|
|
\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 rebuild(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();}
|
|
{Clears the AABB tree. }
|
|
|
|
\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. }
|
|
|
|
% 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{AT} class.}
|
|
|
|
\ccMethod{template <class Query>
|
|
size_t 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_t 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. 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> any_intersected_primitive(const Query& query);}
|
|
{Returns the first encountered intersected primitive, iff the query intersects at least one of the input primitives. Type \ccc{Query} must be a type for which \ccc{do_intersect} and intersection 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{Point_and_primitive}. 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<Point_and_primitive> any_intersection(const Query& query);}
|
|
{Returns the first encountered intersection, iff the query intersects at least one of the input primitives. 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{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). 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{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 Primitive& hint);}
|
|
{Returns the primitive which realizes the smallest distance between the query point and all input primitives. Parameter \ccc{hint} is assumed to be any input primitive (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 is taken as the first primitive. }
|
|
|
|
\ccMethod{Point_and_primitive
|
|
closest_point_and_primitive(const Point& query,
|
|
const Point_and_primitive& 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{reference_point} from the primitive.}
|
|
|
|
\begin{ccAdvanced}
|
|
\ccMethod{template <class InputIterator>
|
|
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. Iterator \ccc{InputIterator} should have \ccc{Point_and_primitive} as value type. 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}
|
|
|
|
\ccSeeAlso
|
|
|
|
\ccc{AABBTraits}, \\
|
|
\ccc{AABBPrimitive}.
|
|
|
|
\end{ccRefClass}
|
|
|
|
% +------------------------------------------------------------------------+
|
|
%%RefPage: end of main body, begin of footer
|
|
\ccRefPageEnd
|
|
% EOF
|
|
% +------------------------------------------------------------------------+
|
|
|