cgal/Spatial_searching/doc_tex/Spatial_searching_ref/Point_container.tex

% +------------------------------------------------------------------------+
% | Reference manual page: Point_container.tex
% +------------------------------------------------------------------------+
% | 1.07.2001   Johan W.H. Tangelder
% | Package: ASPAS
% |
\RCSdef{\RCSPointcontainerRev}{$Id$}
\RCSdefDate{\RCSPointcontainerDate}{$Date$}
% |
%%RefPage: end of header, begin of main body
% +------------------------------------------------------------------------+


\begin{ccRefClass}{Point_container<Traits>}

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


\begin{ccAdvanced}


\ccDefinition
A custom container for points used to build a tree. Each point container
holds the points from a rectangle associated with a node of the tree.
In the remainder of this reference page this rectangle is called the
associated rectangle.
Provides a method to split a container and a number of methods
to support the implementation of splitting rules.

\ccInclude{CGAL/Point_container.h}

\ccParameters

Expects for the template argument an implementation for
$d$-dimensional points of the concept \ccc{SearchTraits}, for example
\ccc{CGAL::Cartesian_d<double>}.

\ccTypes

\ccTypedef{Traits::FT FT;}{Number type.}
\ccTypedef{Traits::Point_d Point_d;}{Point type.}
\ccNestedType{iterator}{An iterator with value type \ccc{Point_d*}.}
\ccNestedType{const_iterator}{A const iterator with value type \ccc{const Point_d*}.}

%----------------------------------------
\ccCreation
\ccCreationVariable{c}

\ccConstructor{Point_container(int d);}
{
Construct an empty container for storing \ccc{d}-dimensional points.
}

\ccConstructor{
template <class InputIterator>
Point_container(int d, InputIterator begin, InputIterator end);}
{
Construct the container of $d$-dimensional points of type \ccc{Point_d}
given by the iterator sequence \ccc{[begin, end)}.}



\ccOperations

\ccMethod{template <class SpatialSeparator>
void split(Point_container<Traits> &c2, SpatialSeparator sep, bool sliding=false);}
{Given an empty container \ccc{c2} with the same dimension as \ccVar, splits \ccVar\ into
\ccVar and \ccc{c2} using the separator \ccc{sep}. If sliding is \ccc{true} after splitting 
each container contains at least one point. Container \ccVar\ should contain at least two points.}


\ccMethod{void swap(Point_container<Traits> &c2);}
{Swap the contents of \ccVar\ and \ccc{c2}}


\ccMethod{void recompute_tight_bounding_box();}
{Recompute the bounding box of the points in the container.}


\ccMethod{iterator begin();}
{
Return an iterator pointing to the pointer to the first point.
}

\ccMethod{iterator end();}
{
Return the iterator to the corresponding past-the-end iterator.
}

\ccMethod{const_iterator begin() const;}
{
Return a const iterator pointing to the pointer to the first point.
}

\ccMethod{const_iterator end() const;}
{
Return a const iterator to the corresponding past-the-end iterator.
}

\ccMethod{int dimension() const;}
{
Return the dimension.
}

\ccMethod{int built_coordinate() const;}
{
Return coordinate for which the pointer list is built.
}

\ccMethod{int max_span_coord() const;}
{
Return coordinate where the associated rectangle has maximal span.
}

\ccMethod{int max_tight_span_coord() const;}
{
Return coordinate where the point coordinates have maximal span.
}

\ccMethod{FT max_span_lower() const;}
{
Return lower value of the interval corresponding to
\ccc{max_span_coord()}.
}


\ccMethod{FT max_tight_span_lower() const;}
{
Return lower value of the interval corresponding to
\ccc{max_tight_span_coord()}. That is, the smallest
\ccc{max_tight_span_coord()}-th coordinate of the points in
\ccVar.
}


\ccMethod{FT max_span_upper() const;}
{
Return upper value of the interval corresponding to
\ccc{max_span_coord()}.
}

\ccMethod{FT max_span_upper_without_dim(int d) const;}
{
Return upper value of the interval over all dimensions
without taking dimension \ccc{d} into account.
}

\ccMethod{FT max_tight_span_upper() const;}
{
Return upper value of the interval corresponding to
\ccc{max_tight_span_coord()}.
}

\ccMethod{FT  max_spread() const;}
{
Return the size of the interval corresponding to \ccc{max_span_coord()}.
}

\ccMethod{FT max_tight_spread() const;}
{
Return the size of the interval corresponding to \ccc{max_tight_span_coord()}.
}

\ccMethod{FT median(int split_coord) const;}
{
Return the median value of the points stored in the container for
dimension \ccc{split_coord}.
}

\ccMethod{const Kd_tree_rectangle<Traits> & bounding_box() const;}
{Return the associated rectangle.}

\ccMethod{const Kd_tree_rectangle<Traits> & tight_bounding_box();}
{Return the bounding box of the items in associated rectangle.}

\ccMethod{int max_tight_span_coord_balanced(FT aspect_ratio) const;}
{Return the dimension with the maximal point spread, for which after fair splitting
the ratio of the length of the longest side and the smallest side of the bounding box of
the items in associated rectangle,
does not exceed \ccc{aspect_ratio}.}

\ccMethod{FT balanced_fair(int d, FT aspect_ratio);}
{Return the splitting value for fair splitting.}

\ccMethod{FT balanced_sliding_fair(int d, FT aspect_ratio);}
{Return the splitting value for sliding fair splitting.}

\ccMethod{std::size_t size() const;}
{
Return the number of points stored.
}

\ccMethod{bool empty() const;}
{
Return true if no points are present, false otherwise.
}




\ccHeading{Output Routines}

\ccFunction{ template<class Traits>
std::ostream& operator<<(std::ostream& s, Point_container<Traits> c);}
{Prints the point container \ccVar\ to the output stream \ccc{s} and returns \ccc{s}.}


\ccSeeAlso

\ccc{SearchTraits}\\
\ccc{SpatialSeparator}

\end{ccAdvanced}
\end{ccRefClass}

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