% +------------------------------------------------------------------------+ % | CGAL User Manual: reference.tex % +------------------------------------------------------------------------+ % | R-tree User Manual % | % | 31.03.2000 Gabriele Neyer % | Start writing the user manual % | \RCSdef{\hdsRev}{$Revision$} \RCSdefDate{\hdsDate}{$Date$} % +------------------------------------------------------------------------+ \section{Software Engineering Perspectives} %\begin{ccTexOnly} %\begin{figure} %%\psfrag{A}{\footnotesize\ccc{Data}} %%\psfrag{B}{\footnotesize\ccc{Key}} %%\psfrag{C}{\footnotesize\ccc{R_tree_traits}} %%\psfrag{D}{\footnotesize\ccc{R_tree}} %%\psfrag{E}{\footnotesize\ccc{IO_tree_traits}} %%\psfrag{F}{\footnotesize\ccc{IO_tree_traits}} %%\psfrag{G}{\footnotesize\hspace*{-.1cm}\parbox{1.9cm}{Database of tree nodes}} %%\psfrag{H}{\footnotesize\hspace*{-.1cm}\parbox{1.9cm}{Database of leaf nodes}} %%\psfrag{I}{\footnotesize\ccc{choose_subtree}} %%\psfrag{J}{\footnotesize\ccc{split_node}} %%\psfrag{K}{\footnotesize\ccc{split_leaf}} %%\psfrag{L}{\footnotesize\ccc{reinsertion_node}} %%\psfrag{M}{\footnotesize\ccc{reinsertion_leaf}} %%\psfrag{O}{\footnotesize\ccc{R_tree_index}} %%\psfrag{P}{\footnotesize\ccc{R_tree_storage}} %\begin{center} %\includegraphics[width=14cm,clip]{rtree-classes4.eps} %\end{center} \%caption{\label{r-tree-design} R-Tree components} %\end{figure} %\end{ccTexOnly} %\begin{ccHtmlOnly} % % %
% R-Tree components % %
%\end{ccHtmlOnly} % %\begin{ccTexOnly} %Figure~\ref{r-tree-design} shows the different components of the %R-Tree (R$^\star $-Tree) that can be plugged into the tree. %\end{ccTexOnly} %\begin{ccHtmlOnly} %Figure~\ref{r-tree-design} shows the different components of the %R-Tree (R$^\star $-Tree) that can be plugged into the tree. %\end{ccHtmlOnly} The R-Tree has three template arguments (see the figure above). The \ccc{R-tree_traits} class which defines the data handling, the \ccc{R_tree_index} class which defines all \ccc{index} strategies and one traits class which defines the databases and sizes of the tree nodes and leaves. This class is called \ccc{R_tree_storage}. We now describe each component more in detail. Note, for each component CGAL provides example classes or implementations of the most important or most commonly used strategies. \subsubsection{Data handling} In this section we describe how data is handled in the tree. \medskip \noindent {\bf Tree Data}\\ \noindent The tree is designed to handle arbitrary spatial objects (called \ccc{Data}) in arbitrary dimensions. Each node of the tree stores a \ccc{Key} which usually is the bounding box of the \ccc{Key}s of its childs. The tree is designed to be independent of the form of a \ccc{Key}. That is a \ccc{Key} can have arbitrary dimension and arbitrary form (e.g. a $d$-dimensional bounding box, the smallest enclosing $d$-dimensional ball, etc). Nevertheless, the \ccc{Key} class has to provide certain properties: E.g. for two \ccc{Key}s it must be decidable if one \ccc{Key} is contained in the other one, if they intersect and what the smallest \ccc{Key} is that encloses both \ccc{Key}s. Besides access functions a \ccc{cost}-function has to be provided that measures the inefficiency when clustering two \ccStyle{Key}s together. This allows the user to build the R-Tree in respect to different optimization functions such as minimum area, overlap or margin enlargement when clustering two \ccStyle{Key}s together. CGAL provides predefined \ccc{Key} classes for $k$-dimensional aligned rectangles, $1\le k\le 4$ (see Section~\ref{k-key}). A traits class implementation that defines all necessary functions is described in Section~\ref{interface}. \medskip \noindent {\bf R\_tree\_traits}\\ \noindent The \ccc{Data} and \ccc{Key} functionality is accessed through a traits class we call \ccc{R_tree_traits}. This traits class decouples the R-tree from the \ccc{Data} and \ccc{Key} class such that a modification of one of these classes only affects this traits class but not the tree. The \ccc{R_tree_traits} class requirements are described in Section~\ref{interface}. \cgal\ provides a predefined \ccc{R_tree_traits} class for the predefined \ccc{Key} classes (see Section~\ref{Rtreetraitspre}). %The %spatial objects are spatially clustered in the tree according to %their orthogonal bounding boxes (called \ccStyle{Key}, see %Section~\ref{k-key}). A \ccStyle{Key} usually is a %$k$-dimensional aligned rectangle, but it is also possible to %define a different geometric object as \ccStyle{Key}. %The \ccc{cost}-function determines the cost of one key or the cost %that arises when two keys are put together. The tree accesses the %\ccc{cost}-function through a traits class and is therefore %independent of the specific cost function. %The user has to provide %key specific functions that measure if two keys intersect, %compute a penalty cost when clustering two keys together, %etc. \subsubsection{R\_tree\_index} The R-Tree index defines how the data is spatially clustered in the tree. We decoupled the index strategies from the implementation of the tree since many diffrent index strategies have been proposed for the R-Tree. \cgal\ provides two \ccc{R_tree_index} classes that can be plugged into the tree: The \ccc{R_tree_index} class which is the index strategy as proposed by Guttman~\cite{g-rtdis-84} and the \ccc{R_star_tree_index} class which is the R$^\star$-Tree index strategy as proposed by Beckmann et al~\cite{bkss-rtera-90} (see Section~\ref{preindex}). The requirements for a user defined \ccc{R_tree_index} class are given in Section~\ref{indexreq}. We here give a short description of the index strategies. \medskip \noindent {\bf choose\_subtree}\\ \noindent In the \ccc{choose-subtree} strategy a subtree is chosen in which the new element is to be inserted. %Many \ccc{choose-subtree} %strategies have been proposed. We therefore decoupled this %strategy from the implementation of the R-Tree. We implemented the \ccc{choose-subtree} strategy from Guttman~\cite{g-rtdis-84} and from Beckmann et al~\cite{bkss-rtera-90} which can be plugged into the tree (see Section~\ref{Choosepre}). The requirements for a user defined \ccc{choose-subtree} strategy are given in Section~\ref{userchoose}. \medskip \noindent {\bf split\_node and split\_leaf}\\ \noindent %Since many merging and splitting strategies have been proposed %for the R-Tree and the R$^\star$-Tree we decoupled these strategies from the %implementation of the R-Tree. The \ccc{split_node} and \ccc{split_leaf} method distributes the entries of an overfilled inner node, resp. leaf, into two. We implemented some important splitting strategies like those from Guttman~\cite{g-rtdis-84} and Beckmann et al~\cite{bkss-rtera-90} which can be plugged into the tree (see Section~\ref{Splitpre}) Note that one can plug in a different split strategy for the inner nodes as for the leaf nodes of the tree. See Section~\ref{userchoose} for the requirements a user implemented split strategy has to fulfill. \medskip \noindent {\bf reinsertion\_node and reinsertion\_leaf}\\ \noindent The R$^\star$-Tree forces entries to be reinserted during the insertion routine. In the \ccc{reinsertion_node} and \ccc{reinsertion_leaf} method, an overfilled node is divided into two parts. The one part stays in that node and the other part is reinserted into the same level of the tree as the node is. %Sine different reinsertion strategies have %been proposed we decoupled these strategies from the %implementation of the R-Tree. We implemented the \ccc{close_reinsert} reinsertion strategy of Beckmann et al~\cite{bkss-rtera-90} which can be plugged into the tree. See Section~\ref{Reinsertpre} for the implementations of the reinsertion strategies and Section~\ref{userreinsert} for the requirements a user implemented reinsertion strategy has to fulfill. \medskip \noindent {\bf reinsertion}\\ \noindent \label{reinsertion} The \ccc{R_tree_index} class gets a boolean template argument \ccc{reinsertion}. In case \ccc{reinsertion=true} entries are reinserted during the insertion process. More precisely, let a node be overfilled. Then, a part of the entries of this node is reinserted in case that no reinsertion in the level of the node has been performed before. The entries that are to be reinserted are chosen in the \ccc{reinsertion_node} class, \ccc{reinsertion_leaf} class, resp. Otherwise, a split is performed. Note, the leaf level is the level number 0. \subsubsection{R\_tree\_storage} The \ccc{R_tree_storage} class is a traits class in which all storage dependant components of the R-Tree are defined. These are a database for the laef nodes, a database for the inner nodes of the tree, the capacities of the nodes in form of the number of elements and the size of a page, etc. \cgal\ provides two predefined \ccc{R_tree_storage} classes called \ccc{R_tree_internal_storage} and \ccc{R_tree_external_storage} that can be plugged into the tree (see Section~\ref{prestorage}). For the requirements of a user defined storage class see Section~\ref{storagereq}. We now give a short description of the components of the \ccc{R_tree_storage} class. \medskip \noindent {\bf Databases}\\ \noindent The R-Tree has two databases. One for the inner nodes of the tree and one for the leaf nodes. Each database is decoupled from the \ccc{R_tree_storage} class by an \ccc{IO_traits} class. %Both databases have to provide the same basic functionality. %We provide an I/O traits class that specifies the %necessary functionality of a database (see Section~\ref{IOpre}). \cgal\ provides two databases for the R-Tree (see Section~\ref{IOpre}). One stores the data and the tree in internal memory. The other database is an external memory database which allocates a memory cache for $k$ pages of size pagesize, whereby $k$ is an integer template argument. The cache uses the least recently used strategy to load and unload pages. Note that other databases can be plugged into the tree by providing an appropriate \ccc{IO_traits} class. See Section~\ref{userIO} for the requirements a user implemented database must fulfill. \medskip \noindent {\bf Node and Leaf Capacities}\\ \noindent The \ccc{R_tree_storage} class gets 4 integer template arguments. The minimum capacity (\ccc{IO_min_cap_nodes}) and maximum capacity (\ccc{IO_max_cap_nodes}) has to be defined for an inner node of the tree. Each inner node is guaranteed to have between \ccc{IO_min_cap_nodes} and \ccc{IO_max_cap_nodes} \ccc{Key} entries; the root node has between 2 and \ccc{IO_max_cap_nodes} entries. For the leaf nodes \ccc{IO_min_cap_leaves} defines the minimum number of elements in a leaf and \ccc{IO_page_size} defines the maximum size of all \ccc{Data} entries of a leaf. \medskip \noindent {\bf headerextern}\\ \noindent \ccc{headerextern} is a boolean template argument. In case \ccc{header_extern=true} a header file containing necessary informations for the reconstruction of a tree from an external database is stored on disk. Otherwise, the header file is not stored on disk. \subsubsection{More Features} \begin{description} \item[reinsertion control] For each level of the tree, a reinsertion flag can be set to \ccc{true} or \ccc{false}. In case that the reinsertion flag of a level is true, the \ccc{reinsertion_node} (\ccc{reinsertion_leaf} resp.) routine will be called for an overfull node of this level (instead of the split routine). When the \ccc{reinsertion_node} (\ccc{reinsertion_leaf} resp.) routine is finished, the reinsertion flag is again set to \ccc{false} for that level. See Section~\ref{r-tree} for a description of the functions \ccc{get_reinsertion_flag} and \ccc{set_reinsertion_flag}. \item[output sensitive query function] The query functions are output sensitive. That is, we provide iterators that allow to intermix user code with querying. Since the amount of query output can exceed the main memory capacity there is no alternative than providing output sensitive query functions (see Section~\ref{r-tree}). \end{description} %The implementation of the R-Tree follows the design issues of the %generalized search tree~\cite{cgal:hnp-gstds-95}. That is, the tree is %designed to handle arbitrary geometric objects (called \ccStyle{Data}) in %arbitrary dimension. The traits class for the \ccc{Data} is %described in Section~\ref{data}. The %spatial objects are spatially clustered in the tree according to %their orthogonal bounding boxes (called \ccStyle{Key}, see %Section~\ref{k-key}). A \ccStyle{Key} usually is a %$k$-dimensional aligned rectangle, but it is also possible to %define a different geometric object as \ccStyle{Key}. CGAL provides predefined %key classes for $k$-dimensional aligned rectangles, $1\le k\le %4$. The user has to provide %key specific functions that measure if two keys intersect, %compute a penalty cost when clustering two keys together, %etc. A traits class that defines all necessary functions is %described in Section~\ref{interface}. This traits class is %implemented out for the predefined key classes. %The split strategies and the requirements for user %defined split strategies are given in Section~\ref{split}. %Since the split strategies work on predefined classes that %contain either a key or a data element and some additional %information on these elements, these classes are defined in Section~\ref{cont}. %The definition of the \ccStyle{R_tree} is given in %Section~\ref{r-tree}. In the end of this chapter an example is given. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%R-TREE%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{R-Tree Class} \label{r-tree} \begin{ccClassTemplate}{R_tree} \noindent {\bf Class: R\_tree$<$R\_tree\_traits, R\_tree\_index, R\_tree\_storage$>$} \ccDefinition The R-Tree gets 3 template arguments. \begin{description} \item[\ccc{R_tree_traits}] This class builds the interface to the \ccc{Data} and \ccc{Key}s of the tree. The requirements of this class are defined in Section~\ref{treetraitsreq}. A predefined \ccc{R_tree_traits} class is described in Section~\ref{Rtreetraitspre}. \item[\ccc{R_tree_index}] This class is a traits class in which the index strategies (\ccc{choose_subtree, split_node, split_leaf, reinsertion_node, reinsertion_leaf}) are defined. \cgal\ provides two predefined index traits classes (see Section~\ref{preindex}). The requirements for a user defined index class are given in Section~\ref{indexreq}. \item[\ccc{R_tree_storage}] This class is a traits class in which the storage depending components are defined. These are a database for the laef nodes, a database for the inner nodes of the tree, the capacities of the nodes in form of the number of elements and the size of a page, etc. \cgal\ provides two predefined \ccc{R_tree_storage} classes called \ccc{R_tree_internal_storage} and \ccc{R_tree_external_storage} that can be plugged into the tree (see Section~\ref{prestorage}). For the requirements of a user defined storage class see Section~\ref{storagereq}. %\item[\ccc{Choose_subtree}] This class provides an \ccc{operator()} member %function which gets all entries of a node, and a \ccc{Key} of %a \ccc{Data} entrie that has to be inserted. It returns a node %entrie that specifies the subtree in which the new \ccc{Data} %entrie is to be inserted. The requirements of this % class are defined in Section~\ref{userchoose}. Predefined % \ccc{Choose_subtree} classes are described in Section~\ref{Choosepre}. %\item[\ccc{Split_node}] An overfilled inner node of the tree is % split according to the split strategy that is defined in this % class. The requirements of this % class are defined in Section~\ref{usersplit}. Predefined % \ccc{Split_node} classes are described in Section~\ref{Splitpre}. %\item[\ccc{Split_leaf}] An overfilled leaf of the tree is % split according to the split strategy that is defined in this % class. The requirements of this % class are defined in Section~\ref{usersplit}. Predefined % \ccc{Split_leaf} classes are described in Section~\ref{Splitpre}. %\item[\ccc{Reinsertion_node}] In case that a part of an overfilled %inner node is reinserted, the \ccc{reinsertion_node} strategy, which is %defined in this class, is called. It computes the set of entries %that is to be reinserted. The requirements of this % class are defined in Section~\ref{userreinsert}. Predefined % \ccc{Reinsertion_node} classes are described in % Section~\ref{Reinsertpre}. %\item[\ccc{Reinsertion_leaf}] In case that a part of an overfilled %inner leaf is reinserted, the \ccc{reinsertion_leaf} strategy, which is %defined in this class, is called. It computes the set of entries %that is to be reinserted. The requirements of this % class are defined in Section~\ref{userreinsert}. Predefined % \ccc{Reinsertion_leaf} classes are described in Section~\ref{Reinsertpre}. %\item[\ccc{IO_tree_traits_nodes}] This class specifies the % database for the inner nodes of the tree. The requirements of this % class are defined in Section~\ref{userIO}. Predefined % \ccc{IO_tree_traits_node} classes are described in % Section~\ref{IOpre}. %\item[\ccc{IO_tree_traits_leaf}] This class specifies the % database for the leaf nodes of the tree. The requirements of this % class are defined in Section~\ref{userIO}. Predefined % \ccc{IO_tree_traits_leaf} classes are described in Section~\ref{IOpre}. %\item[\ccc{IO_pagesize}] This integer template argument specifies % the size of a page. The tree and leaf data is stored in disk % blocks of this size. %This size must be smaller than a third of the % size of the % internal memory such that at least three pages can be kept in % internal memory without swapping. %\item[\ccc{header_extern}] The R-Tree gets a boolean template % argument \ccc{header_extern}. In case \ccc{header_extern=true} % a header file containing necessary informations for the % reconstruction of a tree from an external database is stored on % disk. Otherwise the header file is not stored on disk. \end{description} \ccInclude{CGAL/R_tree.h} \ccCreationVariable{R} \ccCreation \ccConstructor{R_tree();}{An empty R-Tree is constructed.} \ccConstructor{R_tree(char *header_file, char *node_data_file, char *leaf_data_file);}{An R-Tree is initialized. In case that the \ccc{header_file} is not empty, the tree expects that \ccc{header_file}, \ccc{node_data_file} and \ccc{leaf_data_file} are files that were generated by the same type of R-Tree as this type is. That is, all template classes have to be identic. Furthermore, the files must belong together. In this case, the tree is build according to the data in the files. Otherwise, if \ccc{header_file} is an empty file, an empty tree is constructed.} \ccOperations %\ccMethod{void ~R_tree();}{The R-Tree is destructed. The databases are % closed.} %\ccMethod{void open(char *header_file, char *node_data_file, % char *leaf_data_file);}{An R-Tree is initialized. In case that % the \ccc{header_file} is not empty, the tree expects that % \ccc{header_file}, \ccc{node_data_file} and % \ccc{leaf_data_file} are files that were generated by the same % type of R-Tree as this type is. That is, all template classes % have to be identic. Furthermore, the files must belong % together. In this case, the tree is build according to the data % in the files. Otherwise, if \ccc{header_file} is an empty file, % an empty tree is constructed.} \ccMethod{void insert(Data& elem);}{A new element is inserted into the tree.} \ccMethod{bool find_key_include(Key a);}{If the tree contains a \ccc{Data} element that is contained in \ccc{Key a}, then \ccc{true} is returned. Otherwise, \ccc{false} is returned.} \ccMethod{bool find_key_intersect(Key a);}{If the tree contains a \ccc{Data} element with a \ccc{Key k} that has non empty intersection with \ccc{Key a}, then \ccc{true} is returned. Otherwise, \ccc{false} is returned.} \ccMethod{bool delete_key(Key& a, Data& elem);}{If the tree contains a \ccc{Data} element with \ccc{Key a}, then \ccc{elem} is set to this \ccc{Data} element and true is returned. Otherwise, false is returned. Note, only one \ccc{Data} element with \ccc{Key a} is deleted. In order to delete another element with \ccc{Key a} you have to repeat the function call.} \ccMethod{int get_rootlevel();}{The level of the root is returned.} \ccMethod{bool get_reinsertion_flag(int the_level);}{The reinsertion flag of \ccc{the_level} is returned.} \ccMethod{bool set_reinsertion_level(unsigned int the_level,bool value);}{The reinsertion flag of level \ccc{the_level} is set to \ccc{value}. If \ccc{value=true} then a part of an overfilled node in level \ccc{the_level} will be reinserted.} \ccMethod{void dump();}{The tree is dumped in a readable way to \ccc{stderr}.} \ccMethod{R_tree::iterator begin_intersect();}{An forward iterator that iterates through all \ccc{Data} elements of the tree is initialized and returned. In order to iterate through all elements of the tree you should compare your actual iterator with the \ccc{end_intersect()} iterator. If both iterators are identical, you reached past the last element.} \ccMethod{R_tree::iterator end_intersect();}{An forward iterator that iterates through all \ccc{Data} elements of the tree is initialized with the last element and returned. In order to iterate through all elements of the tree you should compare your actual iterator with the \ccc{end_intersect()} iterator. If both iterators are identical, you reached past the last element.} \ccMethod{R_tree::iterator begin_intersect(Key k);}{An forward iterator that iterates through all \ccc{Data} elements of the tree that have non empty intersection with \ccc{Key k} is initialized and returned. In order to iterate through all elements of the tree that have non empty intersection with \ccc{Key k} you should compare your actual iterator with the \ccc{end_intersect(k)} iterator. If both iterators are identical, you reached past the last element.} \ccMethod{R_tree::iterator end_intersect(Key k);}{An forward iterator that iterates through all \ccc{Data} elements of the tree that have non empty intersection with \ccc{Key k} is initialized with the last element and returned. In order to iterate through all elements of the tree that have non empty intersection with \ccc{Key k} you should compare your actual iterator with the \ccc{end_intersect(k)} iterator. If both iterators are identical, you reached past the last element.} \ccMethod{R_tree::iterator begin_enclose(Key k);}{An forward iterator that iterates through all \ccc{Data} elements of the tree that enclose \ccc{Key k} is initialized and returned. In order to iterate through all elements of the tree that enclose \ccc{Key k} you should compare your actual iterator with the \ccc{end_enclose(k)} iterator. If both iterators are identical, you reached past the last element.} \ccMethod{R_tree::iterator end_enclose(Key k);}{An forward iterator that iterates through all \ccc{Data} elements of the tree that enclose \ccc{Key k} is initialized with the last element and returned. In order to iterate through all elements of the tree that enclose \ccc{Key k} you should compare your actual iterator with the \ccc{end_enclose(k)} iterator. If both iterators are identical, you reached past the last element.} \ccMethod{R_tree::iterator begin_compare(Key k);}{An forward iterator is initialized and returned. It iterates through all \ccc{Data} elements $a$ of the tree for which \ccc{R_tree_traits::compare(Key k,a)=true} and for all \ccc{p(a)} \ccc{R_tree_traits::compare(Key k,p(a))=true}, whereby \ccc{p(a)} is a key of an ancestor of \ccc{a} in the tree. In order to iterate through all elements of the tree that compare with \ccc{Key k} you should compare your actual iterator with the \ccc{end_compare(k)} iterator. If both iterators are identical, you reached past the last element. Note that the \ccc{compare} function is no where else used in the tree than for this search. Therefore, you can freely define what kind of comparison is to be done.} \ccMethod{R_tree::iterator end_compare(Key k);}{An forward iterator is initialized with the last element and returned. It iterates through all \ccc{Data} elements $a$ of the tree for which \ccc{R_tree_traits::compare(Key k,a)=true} and \ccc{R_tree_traits::compare(Key k,p(a))=true}, whereby \ccc{p(a)} is a key of an ancestor of \ccc{a} in the tree. In order to iterate through all elements of the tree that compare with \ccc{Key k} you should compare your actual iterator with the \ccc{end_compare(k)} iterator. If both iterators are identical, you reached past the last element. Note that the \ccc{compare} function is no where else used in the tree than for this search. Therefore, you can freely define what kind of comparison is to be done.} \end{ccClassTemplate} \begin{ccClass}{R_tree::iterator } \noindent {\bf Class: R\_tree::iterator} \ccDefinition Defines an iterator over R-Tree \ccc{Data} objects. \ccCreationVariable{I} \ccCreation \ccConstructor{R_tree::iterator();}{} \ccOperations \ccMethod{bool operator==(R_tree::iterator & x);}{Let the iterators point on the \ccc{Data} elements \ccc{a} and \ccc{b}. Then, \ccc{R_tree_traits::equal_data(a,b)} is returned.} \ccMethod{bool operator!=(R_tree::iterator& x);}{Let the iterators point on the \ccc{Data} elements \ccc{a} and \ccc{b}. Then, \ccc{!R_tree_traits::equal_data(a,b)} is returned.} \ccMethod{R_tree::iterator& operator=(R_tree::iterator x);}{The iterator is set to iterator \ccc{x}.} \ccMethod{Data operator*();}{The \ccc{Data} element the iterator points to is returned.} \ccMethod{bool is_valid();}{Returns \ccc{true}, if the iterator points on a valid \ccc{Data} element.} \ccMethod{R_tree::iterator& operator++();}{Depending on the query function (intersection, enclose, compare), the iterator is moved to the next element that matches the query in respect to the \ccc{Key} the iterator was initialized with.} \ccMethod{void operator++(int );}{Same as calling \ccc{operator++()}.} \end{ccClass} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%% Predefined Keys %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{R-Tree Traits Class Implementations for Data handling} In this section we describe all predefined classes for the Data handling, that can be plugged into the R-Tree. \subsection{Predefined $k$-dimensional Keys} \label{k-key} \cgal\ provides four key classes for $k\in\{1,\ldots,4\}$. %\begin{ccClassName}{R\_tree\_key\_\tt k\ccFont } \begin{ccClass}{R_tree_key_k} \noindent {\bf Class: R\_tree\_key\_k} \ccDefinition An object of the class \ccClassName\ is a $k$-dimensional iso rectangle. \ccInclude{CGAL/R_tree_key.h} \ccCreationVariable{K} \ccCreation \ccConstructor{R_tree_key_k ();}{Introduces a $k$-dimensional aligned rectangle.} \ccConstructor{R_tree_key_k(int x1_min, int x1_max,..., int xk_min, int xk_max );}{Introduces a $k$-dimensional aligned rectangle initialized with \ccc{int x1_min, int x1_max,..., int xk_min, int xk_max }.} \ccOperations \ccMethod{bool operator==(R_tree_key_kt a);}{ Returns true if \ccc{K} is equal to \ccc{a}.} %\ccMethod{R_tree_key_k operator=(R_tree_key_kFont a);}{ \ccMethod{R_tree_key_k operator=(R_tree_key_k a);}{ Sets \ccc{K} to \ccc{a}.} \ccMethod{double cost();}{ Depending on the dimension $k$ the interval length, area, or volume is returned.} \ccMethod{void unify(R_tree_key_k a, R_tree_key_k b);} {\ccc{K} is set to bounding box of \ccc{a} $\cup $\ccc{b}.} \ccMethod{bool include(R_tree_key_k a);} {Returns true if \ccc{K} includes \ccc{a}.} \ccMethod{bool intersect(R_tree_key_k a);} {Returns true if \ccc{K} and \ccc{a} intersect.} \ccMethod{void intersection(R_tree_key_k a, R_tree_key_k b);} {\ccc{K} is set to \ccc{a} $\cap$ \ccc{b}. This method is only necessary when the R$^\star$-Tree split strategy of Beckman et al~\cite{bkss-rtera-90} is plugged into the tree (see Section~\ref{Splitpre}).} \ccMethod{double center_dist(R_tree_key_k a);} {Computes the center point of \ccc{K} and \ccc{a} and returns the squared Euclidean distance between their center points. This method is only necessary when the R$^\star$-Tree reinsertion strategy of Beckman et al~\cite{bkss-rtera-90} is plugged into the tree (see Section~\ref{Splitpre}).} \ccMethod{void write(fstream& s);} {Writes \ccc{*this} to s.} \ccMethod{void read(fstream& s);} {Reads \ccc{*this} from s.} \ccMethod{void dump(int depth=0);} {Writes \ccc{*this} in a readable way to \ccc{stderr}.} \end{ccClass} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Predefined Sort\_axis Classes for the $k$-dimensional Keys} \label{Presort} \cgal\ provides four \ccc{Sort_axis} classes, one for each predefined $k$-dimensional Key, $k\in\{1,\ldots,4\}$. In fact, these classes also work on user defined $k$-dimensional \ccc{Key} classes that provide $k$ function objects \ccc{compare_1,\dots ,compare_k} each taking two \ccc{Keys} as argument and returning \ccc{true} if the minimum coordinate of the first argument is leftmost. Each class has an \ccc{bool operator()(int split_axis, Container *first, Container *last)} which sorts the sequence \ccc{[first,last[} according to their \ccc{Key}s and the \ccc{split_axis}. In case that \ccc{split_axis} is greater equal than the dimension of the \ccc{Key}, \ccc{false} is returned. Otherwise, true is returned. This class is needed as a template argument for the implementation of the split strategies of Beckmann et.al.~\cite{bkss-rtera-90} (see Section~\ref{Splitpre}). \begin{ccClassTemplate}{sort_axis_key_k_dim} \noindent {\bf Class: sort\_axis\_key\_{\tt k}\_dim$<$Container$>$}\\ \noindent \ccDefinition The class \ccc{Container} defines the type \ccc{Key}. It has a member of type \ccc{Key} which is called \ccc{key}. \ccInclude{CGAL/R_tree_key.h} \ccCreationVariable{S} \ccCreation \ccOperations \ccMethod{bool operator()(int sort_axis, Container *first, Container *last);}{If the number \ccc{sort_axis} is smaller than the dimension of the \ccc{Container::Key}, then, the entries \ccc{[first,last]} are sorted according to the \ccc{sort_axis}-1 th axis and \ccc{true} is returned. The sorting is processed by calling the STL \ccc{stable_sort} function. If the number \ccc{sort_axis} is greater than or equal to the dimension of the \ccc{Container::Key}, then false is returned.\\ \ccc{Precondition:} the $k$-dimensional \ccc{Key} class provides $k$ function objects \ccc{compare_1,\dots ,compare_k} each taking two \ccc{Keys} as argument and returning \ccc{true} if the minimum coordinate of the first argument is leftmost.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Predefined R\_tree\_traits Class} \label{Rtreetraitspre} \begin{ccClassTemplate}{R_tree_traits} \noindent {\bf Class: R\_tree\_traits$<$R\_tree\_data$>$} \cgal\ provides a predefined \ccc{R_tree_traits} for \ccc{Data} classes that have a predefined \ccc{Key} class as member. Furthermore, the \ccc{Data} class has to provide a \ccc{read} and a \ccc{write} function. This traits class is the interface to the \ccc{Data} and the \ccc{Key} of the \ccc{R_tree} class. Therefore, the tree is independent of the \ccc{Data} and \ccc{Key} class. The \ccc{Data} and \ccc{Key} elements are only accessed through this traits class. This has the advantage that a change of the \ccc{Data} or \ccc{Key} class has only impact on the traits class but not on the tree. Furthermore, the traits class allows to plug in arbitrary Data e.g. a \ccc{CGAL::Polygon_2} or a \ccc{CGAL::Segment_2}. Two methods are only necessary, when R$^\star$-Tree split methods or reinsertion methods are plugged into the tree. These methods are highlighted. \ccInclude{CGAL/R_tree_traits.h} \ccCreationVariable{T} \ccTypes \ccTypedef{typedef R_tree_traits Traits;}{} \ccTypedef{typedef R_tree_data::Key Key;}{} \ccTypedef{typedef R_tree_data Data;}{} \ccCreation \ccConstructor{R_tree_traits();} {Introduces a tree traits.} \ccOperations \ccMethod{ size_t size(Data d);} {Returns the size of \ccc{d}. \ccPrecond \ccc{Data} has a member function \ccc{size_t size();}} \ccMethod{Key build(Data &d);} {Returns the key of \ccc{d}.} \ccMethod{double cost(Key a);} {Returns the \ccc{cost} of \ccc{a}.} \ccMethod{double cost(Key a, Key b);} {Returns the \ccc{cost} of \ccc{a}$\cup$\ccc{b}. According to Guttman, here the inefficiency cost of clustering \ccc{a} with \ccc{b} together should returned. More precisely, \ccc{cost(unify(a,b))-cost(a)-cost(b)} is returned.} \ccMethod{Key unify(Key a, Key b);} {Returns the bounding box of \ccc{a} $\cup $\ccc{b}.} \ccMethod{bool include(Key a, Key b);} {Returns true if \ccc{a} includes \ccc{b}.} \ccMethod{bool intersect(Key a, Key b);} {Returns true if \ccc{a} and \ccc{b} intersect.} \ccMethod{Key intersection(Key a, Key b);} {\ccc{K} is set to \ccc{a} $\cap$ \ccc{b}. This method is only necessary when the R$^\star$-Tree split strategy of Beckman et al~\cite{bkss-rtera-90} is plugged into the tree (see Section~\ref{Splitpre}).} \ccMethod{double center_dist(Key a, Key b);}{ Computes the center point of \ccc{K} and \ccc{a} and returns the squared Euclidean distance between their center points. This method is only necessary when the R$^\star$-Tree reinsertion strategy of Beckman et al~\cite{bkss-rtera-90} is plugged into the tree (see Section~\ref{Splitpre}).} \ccMethod{void read(char *s, Data a);} {\ccc{a} is initialized with \ccc{s}. \ccPrecond \ccc{Data} has a member function \ccc{void read(char *s);}} \ccMethod{void write(char *s, Data a);} {\ccc{a} is written to \ccc{s}. \ccc{s} has size \ccc{size(a)}. \ccPrecond \ccc{Data} has a member function \ccc{void write(char *s);}} \ccMethod{void dump(int depth=0);} {Writes the data or the key in a readable way to \ccc{stderr}.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{R-Tree Traits Class Implementations for the R-Tree Index} In this section we describe the predefined \ccc{R_tree_index} classes and their components. \subsection{Predefined R-Tree Index classes} \label{preindex} The \ccc{R_tree} class gets a \ccc{R_tree_index} class as template argument. This class defines all index strategies of the tree. These strategies define how the data is spatially clustered in the tree. \subsubsection{Predefined R-Tree Index Class} Predefined index class that contains the index strategies of the R-Tree of Guttmann~\cite{g-rtdis-84}. \begin{ccClassTemplate}{R_tree_index} \noindent {\bf Class: R\_tree\_index$<$R\_tree\_traits$>$} \ccDefinition \ccInclude{CGAL/R_tree_index.h} \ccTypes \ccTypedef{typedef choose_subtree, R_tree_traits> Choose_subtree;}{Defines the choose subtree strategy (see Section~\ref{Choosepre}).} \ccTypedef{typedef quadratic_split_node, R_tree_traits> Split_node;}{Defines the split strategy for the inner nodes of the tree (see Section~\ref{Splitpre}).} \ccTypedef{typedef quadratic_split_leaf, R_tree_traits> Split_leaf;}{Defines the split strategy for the leaves of the tree (see Section~\ref{Splitpre}).} \ccTypedef{typedef dummy_reinsertion_node, R_tree_traits> Reinsertion_node;}{Defines the reinsertion node strategy (see Section~\ref{Reinsertionpre}).} \ccTypedef{typedef dummy_reinsertion_leaf, R_tree_traits> Reinsertion_leaf;}{Defines the reinsertion leaf strategy (see Section~\ref{Reinsertionpre}).} %\ccMembers \ccTypedef{const static bool reinsertions=false;}{Reinsertions are prohibited} \end{ccClassTemplate} \subsubsection{Predefined R$^\star$-Tree Index Class} Predefined index class that contains the index strategies of the R$^\star$-tree of Beckmann et al~\cite{bkss-rtera-90}. \begin{ccClassTemplate}{R_star_tree_index} \noindent {\bf Class: R\_star\_tree\_index$<$R\_tree\_traits$>$} \ccDefinition \ccInclude{CGAL/R_star_tree_index.h} \ccTypes \ccTypedef{typedef star_choose_subtree, R_tree_traits> Choose_subtree;}{Defines the choose subtree strategy (see Section~\ref{Choosepre}).} \ccTypedef{typedef star_split_node, R_tree_traits, sort_axis_key_2_dim > > Split_node;}{Defines the split strategy for the inner nodes of the tree (see Section~\ref{Splitpre}).} \ccTypedef{typedef star_split_leaf, R_tree_traits, sort_axis_key_2_dim > > Split_leaf;}{Defines the split strategy for the leaves of the tree (see Section~\ref{Splitpre}).} \ccTypedef{typedef reinsertion_node, R_tree_traits> Reinsertion_node;}{Defines the reinsertion node strategy (see Section~\ref{Reinsertionpre}).} \ccTypedef{typedef reinsertion_leaf, R_tree_traits> Reinsertion_leaf;}{Defines the reinsertion leaf strategy (see Section~\ref{Reinsertionpre}).} %\ccMembers \ccTypedef{const static bool reinsertions=true;}{Do reinsertions.} \end{ccClassTemplate} \subsection{Predefined R-Tree Choose Subtree Strategies} \label{Choosepre} The \ccc{R_tree_index} class gets a \ccc{choose_subtree} class as template argument. For a sequence container of node entries and a \ccc{Key} $k$ of a \ccc{Data} element that has to be inserted into the tree, a node entrie is determined and returned. This node entrie specifies the subtree in which the \ccc{Data} element will be inserted. \cgal\ provides the \ccc{choose_subtree} strategy of Guttman~\cite{g-rtdis-84} and the \ccc{star_choose_subtree} strategy of Beckmann et.al.~\cite{bkss-rtera-90}. \subsubsection{Guttman's Choose Subtree Strategy} \begin{ccClassTemplate}{choose_subtree} \noindent {\bf Class: choose\_subtree$<$Container, R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which is of type \ccc{Key} and contains the key of the subtree. The choose subtree method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{choose_subtree();}{} \ccOperations \ccMethod{Container *operator()(Key k, Container *first, Container *last, int level);}{ For each entry in the sequence container \ccc{[first,last]} the area enlargement to include the new \ccc{Key k} is computed. The \ccc{Container} element with the smallest area enlargement is returned. Ties are resolved by choosing the element of smallest area.} \end{ccClassTemplate} \subsubsection{R$^\star$-Tree Choose Subtree Strategy} \begin{ccClassTemplate}{star_choose_subtree} \noindent {\bf Class: star\_choose\_subtree$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which is of type \ccc{Key} and contains the key of the subtree. The choose subtree method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{star_choose_subtree();}{} \ccOperations \ccMethod{Container *operator()(Key k, Container *first, Container *last, int level);}{ If \ccc{level} is the first level of the tree (the leaves are on level 0), then for each entry in the sequence container \ccc{[first,last]} the overlap enlargement to include the new \ccc{Key k} is computed. The \ccc{Container} element with the smallest area enlargement is returned. Ties are resolved by choosing the element with smallest area enlargement. Otherwise, for each entry in the sequence container \ccc{[first,last]} the area enlargement to include the new \ccc{Key k} is computed. The \ccc{Container} element with the smallest area enlargement is returned. Ties are resolved by choosing the element of smallest area.} \end{ccClassTemplate} %\section{Predefined R-Tree Traits Classes} %%%%%%%%%%%%%%%% Split strategies %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Predefined R\_tree Split Strategies} \label{split} \label{Splitpre} The \ccc{R_tree_index} gets two split classes as template arguments. One splits an inner vertex of the tree and one a leaf of the tree. \cgal\ provides the quadratic split strategy from Guttman~\cite{g-rtdis-84}. Furthermore \cgal\ provides an implementation of the split strategy of Beckmann et.al.~\cite{bkss-rtera-90}. \subsubsection{Guttman quadratic split} \begin{ccClassTemplate}{quadratic_split_leaf} \noindent {\bf Class: quadratic\_split\_leaf$<$Container,R\_tree\_traits$>$} %\begin{ccClassName}{quadratic\_split} \ccDefinition The \ccc{Container} has two members: \ccc{ele} is of type \ccc{Data} and contains a data element, and \ccc{key} is of type \ccc{Key} and contains the key of the data element. The split operation works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{quadratic_split_leaf();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > left, back_insert_iterator > right, unsigned int minEntries, unsigned int pagesize);} {The \ccc{Container} elements in \ccc{[first, last]} are subdivided into two vectors: \ccc{left} and \ccc{right}. Firstly, the two data elements \ccc{a} and \ccc{b} in \ccc{[first, last]} are computed with \ccc{R_tree_traits.cost(a,b)} is maximum. \ccc{a} is put into vector \ccc{right} and \ccc{b} is put into vector \ccc{left}. As long as not all elements in \ccc{[first, last]} are put into a vector, the element \ccc{c} with \ccc{R_tree_traits.cost(a,c)} or \ccc{R_tree_traits.cost(b,c)} is minimum is determined and put into the corresponding vector. It is made sure that each vector contains at least \ccc{minEntries} elements and all \ccc{Data} elements of each vector have size at most \ccc{pagesize}.} \end{ccClassTemplate} \begin{ccClassTemplate}{quadratic_split_node} %\begin{ccClassName}{quadratic\_split\_node} \noindent {\bf Class: quadratic\_split\_node$<$Container, R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which is of type \ccc{Key} and contains the key of the subtree. The split operation works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{quadratic_split_node();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, Container *left, Container *right, int minEntries, int maxEntries);}{ The \ccc{Container} elements in \ccc{[first, last]} are subdivided into two sequence containers: \ccc{left} and \ccc{right}. Firstly, the two elements \ccc{a} and \ccc{b} in \ccc{[first, last]} are computed with \ccc{R_tree_traits.cost(a,b)} is maximum. \ccc{a} is put into \ccc{right} and \ccc{b} is put into \ccc{left}. As long as not all elements in \ccc{[first, last]} are put into a sequence container, the element \ccc{c} with \ccc{R_tree_traits.cost(a,c)} or \ccc{R_tree_traits.cost(b,c)} is minimum is determined and put into the corresponding sequence container. It is made sure that each sequence container \ccc{left} and \ccc{right} contains between \ccc{minEntries} and \ccc{maxEntries} entries. } \end{ccClassTemplate} %\subsubsection{Modified Guttman quadratic split % (linear\_split\_leaf, linear\_split\_node)} % %\begin{ccClassTemplate}{linear_split_leaf} % %\noindent %{\bf Class: linear\_split\_leaf$<$Container,R\_tree\_traits$>$} % %%\begin{ccClassName}{quadratic\_split} %\ccDefinition % %The \ccc{Container} has two members: \ccc{ele} is of %type \ccc{Data} and contains a data element, and \ccc{key} is of %type \ccc{Key} and contains the key of the data element. %The split operation works %on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member %functions of class \ccc{R_tree_traits}. % %\ccInclude{CGAL/R_tree_split.h} %\ccCreationVariable{s} % % %\ccCreation %\ccConstructor{linear_split_leaf();}{} % %\ccOperations %\ccMethod{void operator()(Container *first, Container *last, % back_insert_iterator > left, % back_insert_iterator > right, % unsigned int minEntries, unsigned int % pagesize);}{ %The \ccc{Container} elements in \ccc{[first, last]} are % subdivided into two vectors: \ccc{left} and % \ccc{right}. Firstly, the two \ccc{Data} elements \ccc{a} and \ccc{b} % in \ccc{[first, % last]} are computed with \ccc{R_tree_traits.cost(a,b)} is % maximum. \ccc{a} is put into vector \ccc{right} and \ccc{b} is % put into vector \ccc{left}. After that, the rest of the % elements in % \ccc{[first, last]} are put into that vector for which the % the insertion of the element produces a minimum cost. It % is made sure that each vector contains at least % \ccc{minEntries} elements and the \ccc{Data} elements have size % at most \ccc{pagesize}.} % %\end{ccClassTemplate} % % %\begin{ccClassTemplate}{linear_split_node} % %\noindent %{\bf Class: linear\_split\_node$<$Container,R\_tree\_traits$>$} %%\begin{ccClassName}{quadratic\_split\_node} % % %\ccDefinition %The \ccc{Container} has a member %\ccc{key} which is of %type \ccc{Key} and contains the key of the subtree. %The split operation works %on this class. %See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member %functions of class \ccc{R_tree_traits}. % %\ccInclude{CGAL/R_tree_split.h} %\ccCreationVariable{s} %\ccCreation % %\ccConstructor{linear_split_node();}{} % %\ccOperations %\ccMethod{void operator()(Container *first, Container *last, % Container *left, Container *right, % int minEntries, int maxEntries);}{ %The \ccc{Container} elements in \ccc{[first, last]} are % subdivided into two sequence containers: \ccc{left} and % \ccc{right}. Firstly, the two elements \ccc{a} and \ccc{b} % in \ccc{[first, % last]} are computed with \ccc{R_tree_traits.cost(a,b)} is % maximum. \ccc{a} is put into \ccc{right} and \ccc{b} is % put into \ccc{left}. After that, the rest of the % elements in % \ccc{[first, last]} are put into that vector for which the % the insertion of the element produces a minimum cost. It is % made sure that each sequence container % \ccc{left} and \ccc{right} contains between \ccc{minEntries} and % \ccc{maxEntries} entries.} %\end{ccClassTemplate} % \subsubsection{Beckmann R$^\star$-Tree Split Strategy} Implementation of the R$^\star$-Tree split strategy of Beckmann et al~\cite{bkss-rtera-90}. \begin{ccClassTemplate}{star_split_leaf} \noindent {\bf Class: star\_split\_leaf$<$Container,R\_tree\_traits, Sort\_axis$>$} \ccDefinition The \ccc{Container} has two members: \ccc{ele} is of type \ccc{Data} and contains a data element, and \ccc{key} is of type \ccc{Key} and contains the key of the data element. The split operation works on this class. The \ccc{Sort\_axis} class has to provide an \ccc{bool operator()(int sort_axis, Container *first, Container *last)} which sorts the sequence \ccc{[first,last[} according to their \ccc{Key}s and the \ccc{sort_axis}. In case that \ccc{sort_axis} is greater equal than the dimension of the \ccc{Key}, \ccc{false} is returned. \cgal\ provides predefined \ccc{Sort_axis} routines for the predefined \ccc{Keys} (see Section~\ref{Presort}). The requirements for user defined \ccc{Sort_axis} routines are given in Section~\ref{Sortuser}. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{star_split_leaf();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > left, back_insert_iterator > right, unsigned int minEntries, unsigned int pagesize);}{ Along each axis, the entries are first sorted by the lower value, then sorted by the upper value of their rectangles. Let $ele_1,\dots ,ele_k$ be the sorted list of entries. For each sort all distributions of the form $ele_1,\dots ,ele_j$ and $ele_{j+1},\dots ,ele_k$ are computed, such that in each distribution the minimum number of entries is at least \ccc{minEntries} and the size of the \ccc{Data} elements is at most \ccc{pagesize}. For each distribution margin values are determined. Depending on these goodness values the final distribution of the entries is determined. The split axis with minimum margin value is determined and a distribution with minimum overlap-value is chosen. Ties are resolved by choosing the distribution with minimum area-value. The entries of the distributions are inserted into the sequence containers \ccc{left} and \ccc{right}.} \end{ccClassTemplate} \begin{ccClassTemplate}{star_split_node} \noindent {\bf Class: star\_split\_node$<$Container, R\_tree\_traits, Sort\_axis$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which is of type \ccc{Key} and contains the key of the subtree. The split operation works on this class. The \ccc{Sort\_axis} class has to provide an \ccc{bool operator()(int sort_axis, Container *first, Container *last)} which sorts the sequence \ccc{[first,last[} according to their \ccc{Key}s and the \ccc{sort_axis}. In case that \ccc{sort_axis} is greater equal than the dimension of the \ccc{Key}, \ccc{false} is returned. \cgal\ provides predefined \ccc{Sort_axis} routines for the predefined \ccc{Keys} (see Section~\ref{Presort}). The requirements for user defined \ccc{Sort_axis} routines are given in Section~\ref{Sortuser}. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{star_split_node();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, Container *left, Container *right, int minEntries, int maxEntries);}{ Along each axis, the entries are first sorted by the lower value, then sorted by the upper value of their rectangles. Let $ele_1,\dots ,ele_k$ be the sorted list of entries. For each sort all distributions of the form $ele_1,\dots ,ele_j$ and $ele_{j+1},\dots ,ele_k$ are computed, such that in each distribution the minimum number of entries is at least \ccc{minEntries} and the maximum number of entries is at most \ccc{maxEntries}. For each distribution margin values are determined. Depending on these goodness values the final distribution of the entries is determined. The split axis with minimum margin value is determined and a distribution with minimum overlap-value is chosen. Ties are resolved by choosing the distribution with minimum area-value. The entries of the distributions are inserted into the sequence containers \ccc{left} and \ccc{right}.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Predefined R\_tree Reinsertion Strategies} \label{Reinsertpre} \label{Reinsertionpre} The \ccc{R_tree_index} class gets a \ccc{reinsertion_leaf} and a \ccc{reinsertion_node} class as template arguments. The reinsertion methods are called when a node is overfilled and the reinsertion flag of the level of this node is true (see Section~\ref{reinsertion}). A sequence container of leaf entries (node entries, resp.) has to be subdivided into two sequence containers \ccc{new_elements} and \ccc{to_reinsert}. The elements of the first container get the elements of the actual node, the elements of the second container will be reinserted into the tree. \cgal\ provides the \ccc{reinsertion_leaf} and \ccc{reinsertion_node} strategy of Beckmann et.al.~\cite{bkss-rtera-90}. In case that your tree is not to perform reinsertion, we provide two dummy classes \ccc{dummy_reinsertion_leaf} and \ccc{dummy_reinsertion_node} that can be plugged in the tree and do nothing. \subsubsection{R$^\star$-Tree Reinsertion Strategy} \begin{ccClassTemplate}{reinsertion_leaf} \noindent {\bf Class: reinsertion\_leaf$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has two members: \ccc{ele} is of type \ccc{Data} and contains a data element, and \ccc{key} is of type \ccc{Key} and contains the key of the data element. The reinsertion node method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{reinsertion_leaf();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > new_elements, back_insert_iterator > to_reinsert, unsigned int minEntries, unsigned int pagesize);}{ For each entry in the sequence container \ccc{[first,last]} the distances between the centers of their rectangles and the center of the bounding rectangle of the entries are computed. The entries are sorted in decreasing order of their distances. Then, the first 30 $\%$ of the entries is put into the sequence container \ccc{to_reinsert} and the rest in \ccc{new_elements}. It is made sure that the sum of the \ccc{Data} sizes of the entries in \ccc{new_elements} is at most \ccc{pagesize}. Furthermore, the number of entries in \ccc{new_entries} is at least \ccc{minEntries}.} \end{ccClassTemplate} \begin{ccClassTemplate}{reinsertion_node} \noindent {\bf Class: reinsertion\_node$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which has type \ccc{Key} and contains the key of the subtree. The reinsertion node method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{reinsertion_node();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > new_elements, back_insert_iterator > to_reinsert, unsigned int minEntries, unsigned int maxEntries);}{ For each entry in the sequence container \ccc{[first,last]} the distances between the centers of their rectangles and the center of the bounding rectangle of the entries are computed. The entries are sorted in decreasing order of their distances. Then, the first 30 $\%$ of the entries is put into the sequence container \ccc{to_reinsert} and the rest in \ccc{new_elements}. It is made sure that the sum of the \ccc{Data} sizes of the entries in \ccc{new_elements} is at most \ccc{pagesize}. Furthermore, the number of entries in \ccc{new_entries} is at least \ccc{minEntries}.} \end{ccClassTemplate} \begin{ccClassTemplate}{dummy_reinsertion_leaf} \noindent {\bf Class: dummy\_reinsertion\_leaf$<$Container,R\_tree\_traits$>$} \ccDefinition Dummy class that can be plugged into the tree in case that reinsertion is prohibited. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{dummy_reinsertion_leaf();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > new_elements, back_insert_iterator > to_reinsert, unsigned int minEntries, unsigned int pagesize);}{ Does nothing.} \end{ccClassTemplate} \begin{ccClassTemplate}{dummy_reinsertion_node} \noindent {\bf Class: dummy\_reinsertion\_node$<$Container,R\_tree\_traits$>$} \ccDefinition Dummy class that can be plugged into the tree in case that reinsertion is prohibited. \ccInclude{CGAL/R_tree_index_implementations.h} \ccCreationVariable{s} \ccCreation \ccConstructor{dummy_reinsertion_node();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > new_elements, back_insert_iterator > to_reinsert, unsigned int minEntries, unsigned int maxEntries);}{ Does nothing.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{R-Tree Traits Class Implementations for the R-Tree storage} In this section we describe the predefined \ccc{R_tree_storage} classes and their components. \subsection{Predefined R-Tree Internal Storage Class} \cgal\ provides a storage class that defines two internal memory databases as databases for the tree. \begin{ccClass}{R_tree_internal_storage} \noindent {\bf Class: R\_tree\_internal\_storage} \ccDefinition \ccInclude{CGAL/R_tree_internal_storage.h} \ccTypes \ccTypedef{typedef R_tree_internal_db IO_tree_traits_nodes;}{Defines the \ccc{R_tree_internal_db} to be the database for the nodes of the tree. See Section~\ref{internalpre} for the definition of this database.} \ccTypedef{typedef R_tree_internal_db IO_tree_traits_leaves;}{Defines the \ccc{R_tree_internal_db} to be the database for the leaves of the tree. See Section~\ref{internalpre} for the definition of this database.} \ccTypedef{const static unsigned int IO_min_cap_nodes=2;}{Each inner node must have at least two entries.} \ccTypedef{const static unsigned int IO_max_cap_nodes=4;}{Each inner node has at most four entries.} \ccTypedef{const static unsigned int IO_min_cap_leaves=2;}{Each leaf node must have at least two entries.} \ccTypedef{const static unsigned int IO_page_size=70;}{One page of \ccc{Data} has size 70.} \ccTypedef{const static bool headerextern=false;}{The header of the tree is hold in internal memory.} \end{ccClass} \subsection{Predefined R-Tree External Storage Class} \label{prestorage} \cgal\ provides a storage class that defines two internal memory databases as databases for the tree. \begin{ccClass}{R_tree_external_storage} \noindent {\bf Class: R\_tree\_external\_storage} \ccDefinition \ccInclude{CGAL/R_tree_external_storage.h} \ccTypes \ccTypedef{typedef R_tree_external_db IO_tree_traits_nodes;}{Defines the \ccc{R_tree_external_db} to be the database for the nodes of the tree. See Section~\ref{externalpre} for the definition of this database.} \ccTypedef{typedef R_tree_external_db IO_tree_traits_leaves;}{Defines the \ccc{R_tree_external_db} to be the database for the leaves of the tree. See Section~\ref{externalpre} for the definition of this database.} \ccTypedef{const static unsigned int IO_min_cap_nodes=2;}{Each inner node must have at least two entries.} \ccTypedef{const static unsigned int IO_max_cap_nodes=4;}{Each inner node has at most four entries.} \ccTypedef{const static unsigned int IO_min_cap_leaves=2;}{Each leaf node must have at least two entries.} \ccTypedef{const static unsigned int IO_page_size=70;}{One page of \ccc{Data} has size 70.} \ccTypedef{const static bool headerextern=true;}{The header of the tree is hold in external memory. This allows to rebuild the tree from its files.} \end{ccClass} \subsection{Predefined R-Tree Databases} \label{IOpre}\label{iopre} The \ccc{R_tree} gets two Input/Output traits classes as template arguments. One is the interface to the database for the \ccc{Data} entries of the tree and the other one is the interface to the database in which the nodes of the tree are to be stored. \cgal\ provides two databases. One that stores the data in internal memory and one that stores the data on disk. An R-tree can be restored from disk if the node data and the \ccc{Data} entries were stored in external memory. These databases can be plugged into the tree directly. \subsubsection{Predefined Internal Memory R-Tree Database} \label{internalpre} \begin{ccClass}{R_tree_internal_db} \noindent {\bf Class: R\_tree\_internal\_db} \ccDefinition In this database, all entries are stored in internal memory. The following functions are used by the R-Tree. \ccInclude{CGAL/R_tree_internal_db.h} \ccCreationVariable{R} \ccCreation \ccConstructor{R_tree_internal_db(unsigned int pagesize, char* name, int m = fstream::ate, int prot = filebuf::openprot);} {Introduces a database in internal memory. All elements that are written to or read from the database have size \ccc{pagesize}. 100 pages of size \ccc{pagesize} are initially allocated. The number of pages is doubled whenever all pages are in use.} \ccOperations \ccMethod{void close();}{The allocated memory is given free.} \ccMethod{difference_type get_pos();}{A new position for a new page that will be inserted is returned.} \ccMethod{bool insert(difference_type pos, char **x);}{A page \ccc{x} is written into internal memory at reference position \ccc{pos}. The position of the page must have been returned by method \ccc{get_pos()}. Necessary global informations like the number of elements are updated.} \ccMethod{bool update(difference_type pos, char** x);}{The page at reference position \ccc{pos} is overwritten with x.} \ccMethod{bool get(difference_type pos, char **x);}{The page at reference position \ccc{pos} is written into \ccc{x}. \ccc{x} has to provide \ccc{pagesize} space.} \ccMethod{bool erase(difference_type pos);}{The page at position \ccc{pos} is erased. The page is inserted into a list of free pages and will be reused.} \ccMethod{bool deleted(difference_type pos);}{If the page at position \ccc{pos} is in use \ccc{true} is returned. Otherwise, \ccc{false} is returned.} \end{ccClass} \subsubsection{Predefined External Memory R-Tree Database} \label{externalpre} \begin{ccClassTemplate}{R_tree_external_db} \noindent {\bf Class: R\_tree\_external\_db$<$pages\_in\_cache$>$} \ccDefinition In this database, all entries are stored in external memory. The class gets an unsigned integer argument \ccc{pages_in_cache} as a template argument. This argument specifies the number of pages that are kept in internal memory. The database uses the least recently used strategy to load and unload pages in internal memory. More precisely, the pages in internal memory are stored in a list. Whenever an element is touched (updated, requested,...) it is put at the front of that list. When an element that is not in the list has to be retrieved from external memory, then this element is put at the front of the list and the element at the back of that list is written on external memory. Each element has a flag \ccc{dirty}. Whenever this flag is set \ccc{true}, the element in cache differs from that in external memory. With this flag unnecessary external memory accesses are avoided. The following functions are used by the R-Tree. \ccInclude{CGAL/R_tree_external_db.h} \ccCreationVariable{R} \ccCreation \ccConstructor{R_tree_external_db(unsigned int pagesize, char* name, int m = fstream::ate, int prot = filebuf::openprot);} {Introduces a database in external memory with the name \ccc{name}. All elements that are written to or read from the database have size \ccc{pagesize}. The cache of \ccc{pages_in_cache} pages of size \ccc{pagesize} is initialized.} \ccOperations \ccMethod{void close();}{All pages of the \ccc{cache} that are marked dirty are written to external memory. The allocated memory is given free and the file is closed.} \ccMethod{difference_type get_pos();}{A new position for a new page that will be inserted is returned.} \ccMethod{bool insert(difference_type pos, char **x);}{A page \ccc{x} is inserted into the database with reference position \ccc{pos}. The position of the page must have been returned by method \ccc{get_pos()}. The last page in the cache is written to external memory, if it is marked dirty. Then, the page \ccc{x} is written into that page of the cache and marked dirty. The page is put at the first position of the cache. Necessary global informations like the number of elements are updated.} \ccMethod{bool update(difference_type pos, char** x);}{The page at reference position \ccc{pos} is overwritten with \ccc{x}. It is checked if the page is in the cache. In this case, the page is updated and marked dirty. Otherwise, the last page in the cache is written on external memory, if it is marked dirty. Then, the page is retrieved from external memory into that page of the cache, updated and marked dirty. In both cases, the page is put at the first position of the cache.} \ccMethod{bool get(difference_type pos, char **x);}{The page at reference position \ccc{pos} is written into \ccc{x}. \ccc{x} has to provide \ccc{pagesize} space. It is checked if the page is in the cache. In this case, the page is returned. Otherwise, the page is retrieved from external memory. The last page in the cache is written to external memory, if it is marked dirty. The page is put at the first position of the cache.} \ccMethod{bool erase(difference_type pos);}{The page at position \ccc{pos} is erased. If the page is internal memory, it is simply marked deleted and marked dirty. Otherwise, it is retrieved from disk and marked deleted there. The page is inserted into a list of free pages and will be reused.} \ccMethod{bool deleted(difference_type pos);}{If the page at position \ccc{pos} is not marked deleted \ccc{true} is returned. Otherwise, \ccc{false} is returned.} \end{ccClassTemplate} %The advanced user can implement her own split %strategy by providing the interface and functionality of the %split strategies described below. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%% Traits Requirements %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Requirements for the R-Tree Traits Class} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{R\_tree\_traits Class Requirements} \label{interface} \begin{ccClassTemplate}{R_tree_traits} \label{treetraitsreq} \noindent {\bf Class: R\_tree\_traits$<$R\_tree\_data$>$} This traits class is the interface to the \ccc{Data} and the \ccc{Key} of the \ccc{R_tree} class. Therefore, the tree is independent of the \ccc{Data} and \ccc{Key} class. The \ccc{Data} and \ccc{Key} elements are only accessed through this traits class. This has the advantage that a change of the \ccc{Data} or \ccc{Key} class has only impact on the traits class but not on the tree. Furthermore, the traits class allows to plug in arbitrary Data e.g. a \ccc{CGAL::Polygon_2} or a \ccc{CGAL::Segment_2}. Two methods are only necessary, when R$^\star$-Tree split methods or reinsertion methods are plugged into the tree. These methods are highlighted. \ccInclude{CGAL/R_tree_traits.h} \ccCreationVariable{T} \ccTypes \ccTypedef{typedef Traits;}{The type of this traits class} \ccTypedef{typedef Key;}{The type of the \ccc{Key}s} \ccTypedef{typedef Data;}{The type of the \ccc{Data}} \ccCreation \ccConstructor{R_tree_traits();} {Introduces a tree traits.} \ccOperations \ccMethod{ size_t size(Data d);} {The size of \ccc{d} has to be returned.} \ccMethod{Key build(Data &d);} {The key of \ccc{d} has to be returned.} \ccMethod{double cost(Key a);} {The \ccc{cost} of \ccc{a} has to be returned.} \ccMethod{double cost(Key a, Key b);} { A cost when clustering \ccc{a} with \ccc{b} together has to be returned. According to Guttman, here the inefficiency cost of clustering \ccc{a} with \ccc{b} together should be returned. We suggest returning \ccc{cost(unify(a,b))-cost(a)-cost(b)}.} \ccMethod{Key unify(Key a, Key b);} {The bounding \ccc{Key} of \ccc{a} $\cup $\ccc{b} has to be returned.} \ccMethod{bool include(Key a, Key b);} {True has to be returned if \ccc{a} includes \ccc{b}. Otherwise, false.} \ccMethod{bool intersect(Key a, Key b);} {True has to be returned if \ccc{a} and \ccc{b} intersect. Otherwise, false.} \ccMethod{Key intersection(Key a, Key b);} {A \ccc{Key k}$=$ \ccc{a} $\cap$ \ccc{b} has to be returned. This method is only necessary when the R$^\star$-Tree split strategy of Beckman et al~\cite{bkss-rtera-90} is plugged into the tree.} \ccMethod{double center_dist(Key a, Key b);} {The distance between the centers of \ccc{a} and \ccc{b} has to be returned. This method is only necessary when the R$^\star$-Tree reinsertion strategy of Beckman et al~\cite{bkss-rtera-90} is plugged into the tree.} \ccMethod{void read(char *s, Data a);} {\ccc{a} has to be initialized with \ccc{s}.} \ccMethod{void write(char *s, Data a);} {\ccc{a} has to be written to \ccc{s}. \ccc{s} has size \ccc{size(a)}.} \ccMethod{void dump(int depth=0);} {Write the data or the key in a readable way to \ccc{stderr}.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Requirements of a User Defined Sort\_axis Class} \label{Sortuser} The predefined split strategy implementation of Beckmann et.al.~\cite{bkss-rtera-90} need a \ccc{Sort_axis} class template argument (see Section~\ref{Splitpre}). This class has to provide an \ccc{bool operator()(int sort_axis, Container *first, Container *last)} which sorts the sequence \ccc{[first,last[} according to their \ccc{Key}s and the \ccc{sort_axis}. In case that \ccc{sort_axis} is greater equal than the dimension of the \ccc{Key}, \ccc{false} has to be returned. Otherwise, true has to be returned. \begin{ccClass}{Sort_axis} \noindent {\bf Class: Sort\_axis} \ccCreationVariable{S} \ccOperations \ccMethod{bool operator()(int sort_axis, Container *first, Container *last);}{ The class \ccc{Container} typdefs the \ccc{Key} type of the \ccc{Key}s of the tree. Furthermore, it has a member \ccc{key} which is the \ccc{Key} of the \ccc{Container} entrie. If the number \ccc{sort_axis} is smaller than the dimension of the \ccc{Container::Key}, then, the entries \ccc{[first,last]} have to be sorted according to the \ccc{sort_axis}-1 th axis and \ccc{true} has to be returned. That is, the \ccc{key}s of the \ccc{Container} elements have to be sorted according to the \ccc{sort_axis}-1 th dimension. If the number \ccc{sort_axis} is greater than or equal to the dimension of the \ccc{Container::Key}, false has to be returned.} \end{ccClass} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Requirements for a User Defined R-Tree Index} In this section we describe the requirements for a user defined \ccc{R_tree_index} class and its components. \subsection{Requirements for User Defined R-Tree Index classes} \label{indexreq} The \ccc{R_tree} class gets a \ccc{R_tree_index} class as template argument. This class defines all index strategies of the tree. These strategies define how the data is spatially clustered in the tree. We now describe the types and members such a class has to provide. \begin{ccClass}{R_tree_index} \noindent {\bf Class: R\_tree\_index} \ccTypes \ccTypedef{typedef Choose_subtree;}{Definition of the choose subtree strategy. For the requirements on this type see Section~\ref{userchoose}, for predefined choose subtree classes see Section~\ref{Choosepre}.} \ccTypedef{typedef Split_node;}{Definition of the split strategy for the inner nodes of the tree. For the requirements on this type see Section~\ref{usersplit}, for predefined split classes see Section~\ref{Splitpre}.} \ccTypedef{typedef Split_leaf;}{Definition of the split strategy for the leaf nodes of the tree. For the requirements on this type see Section~\ref{usersplit}, for predefined split classes see Section~\ref{Splitpre}.} \ccTypedef{typedef Reinsertion_node;}{Definition of the reinsertion strategy for the inner nodes of the tree. For the requirements on this type see Section~\ref{userreinsert}, for predefined split classes see Section~\ref{Reinsertionpre}.} \ccTypedef{typedef Reinsertion_leaf;}{Definition of the reinsertion strategy for the leaf nodes of the tree. For the requirements on this type see Section~\ref{userreinsert}, for predefined split classes see Section~\ref{Reinsertionpre}.} \ccTypedef{const static bool reinsertions;}{If \ccc{reinsertions=true} then, reinsertions are performed during the insertion process. Otherwise, reinsertions are prohibited.} \end{ccClass} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%Requirements for Choose Subtree Strategies %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Requirements for a User Defined Choose Subtree Strategy} \label{userchoose} The \ccc{R_tree} gets a \ccc{choose_subtree} class as template argument. This class has to provide an \ccc{operator()} member function. For a sequence container of node entries and a \ccc{Key} $k$ of a \ccc{Data} element that has to be inserted into the tree, a node entrie is determined and returned. This node entrie specifies the subtree in which the \ccc{Data} element will be inserted. \begin{ccClassTemplate}{choose_subtree} \noindent {\bf Class: choose\_subtree$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which is of type \ccc{Key} and contains the key of the subtree. The choose subtree method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccCreationVariable{s} \ccCreation \ccConstructor{choose_subtree();}{} \ccOperations \ccMethod{Container *operator()(Key k, Container *first, Container *last, int level);}{ One of the entries in the sequence container \ccc{[first,last]} has to be chosen and returned. In the subtree belonging to this entry, the data element with \ccc{Key k} will be inserted.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%% Split Strategy %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Requirements for User Defined Split Strategies} \label{usersplit} The \ccc{R_tree} gets two split classes as template arguments. One splits an inner vertex of the tree and one a leaf of the tree. These split strategies are classes that provide an operator() member function which we describe below. The split strategy has to distribute the leaf data (node data, resp.) elements into two, such that in each set the minimum capacity of a node is exceeded and the maximum capacity is not exceeded. The goal is to find split strategies that cluster elements together, that are spatially close to each other. \begin{ccClassTemplate}{split_leaf} \noindent {\bf Class: split\_leaf$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has two members: \ccc{ele} is of type \ccc{Data} and contains a data element, and \ccc{key} is of type \ccc{Key} and contains the key of the data element. The split operation works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccCreationVariable{s} \ccCreation \ccConstructor{star_split_leaf();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > left, back_insert_iterator > right, unsigned int minEntries, unsigned int pagesize);}{ The elements in \ccc{[first,last]} have to be distributed in two sequence containers \ccc{left, right} such that each sequence container contains at least \ccc{minEntries} entries and the data elements of a sequence container together, have size at most \ccc{pagesize}.} \end{ccClassTemplate} \begin{ccClassTemplate}{split_node} \noindent {\bf Class: split\_node$<$Container, R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which is of type \ccc{Key} and contains the key of the subtree. The split operation works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccCreationVariable{s} \ccCreation \ccConstructor{split_node();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, Container *left, Container *right, int minEntries, int maxEntries);}{ The elements in \ccc{[first,last]} have to be distributed in two sequence containers \ccc{left, right} such that each sequence container contains at least \ccc{minEntries} entries and at most \ccc{maxEntries} entries.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%% Requirements for Reinsertion Routine %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Requirements for User Defined Reinsertion Strategies} \label{userreinsert} \label{reinsertreq} The \ccc{R_tree} gets a \ccc{reinsertion_leaf} and a \ccc{reinsertion_node} class as template arguments. The reinsertion methods are called when a node is overfilled and the reinsertion flag of the level of this node is true (see Section~\ref{reinsertion}). A sequence container of leaf entries (node entries, resp.) has to be subdivided into two sequence containers \ccc{new_elements} and \ccc{to_reinsert}. The elements of the first container get the elements of the actual node, the elements of the second container will be reinserted into the tree. \begin{ccClassTemplate}{reinsertion_leaf} \noindent {\bf Class: reinsertion\_leaf$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has two members: \ccc{ele} is of type \ccc{Data} and contains a data element, and \ccc{key} is of type \ccc{Key} and contains the key of the data element. The reinsertion node method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccCreationVariable{s} \ccCreation \ccConstructor{reinsertion_leaf();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > new_elements, back_insert_iterator > to_reinsert, unsigned int minEntries, unsigned int pagesize);}{ Each entry in the sequence container \ccc{[first,last]} either has to be inserted into the sequence container \ccc{new_elements} or into the sequence container \ccc{to_reinsert}. The elements in the sequence container \ccc{new_elements} stay in the node. The elements in the sequence container \ccc{to_reinsert} are reinserted in the same level of the tree as the actual node is. The number of elements in the sequence container \ccc{new_elements} has to be at least \ccc{minEntries}. The size of all \ccc{Data} elements in the sequence container \ccc{new_elements} must not exceed \ccc{pagesize}.} \end{ccClassTemplate} \begin{ccClassTemplate}{reinsertion_node} \noindent {\bf Class: reinsertion\_node$<$Container,R\_tree\_traits$>$} \ccDefinition The \ccc{Container} has a member \ccc{key} which has type \ccc{Key} and contains the key of the subtree. The reinsertion node method works on this class. See Section~\ref{Rtreetraitspre} and~\ref{treetraitsreq} for the definition and member functions of class \ccc{R_tree_traits}. \ccCreationVariable{s} \ccCreation \ccConstructor{reinsertion_node();}{} \ccOperations \ccMethod{void operator()(Container *first, Container *last, back_insert_iterator > new_elements, back_insert_iterator > to_reinsert, unsigned int minEntries, unsigned int maxEntries);}{ Each entry in the sequence container \ccc{[first,last]} either has to be inserted into the sequence container \ccc{new_elements} or into the sequence container \ccc{to_reinsert}. The elements in the sequence container \ccc{new_elements} stay in the node. The elements in the sequence container \ccc{to_reinsert} are reinserted in the same level of the tree as the actual node is. The number of elements in the sequence container \ccc{new_elements} has to be at least \ccc{minEntries} and at most \ccc{maxEntries}.} \end{ccClassTemplate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \section{Requirements for a User Defined Storage Class} \label{storagereq} A user defined storage class must provide the following types and members: \begin{ccClass}{R_tree_storage} \noindent {\bf Class: R\_tree\_storage} \ccTypes \ccTypedef{typedef IO_tree_traits_nodes;}{Definition of the database for the nodes of the tree. See Section~\ref{IOpre} for predefined databases and see Section~\ref{userIO} for the requirements for this database.} \ccTypedef{typedef R_tree_internal_db;}{Definition of the database for the leaves of the tree. See Section~\ref{IOpre} for predefined databases and see Section~\ref{userIO} for the requirements for this database.} \ccTypedef{const static unsigned int IO_min_cap_nodes;}{Definition of the minimum number of entries in an innner node of the tree.} \ccTypedef{const static unsigned int IO_max_cap_nodes;}{Definition of the maximum number of entries in an inner node of the tree.} \ccTypedef{const static unsigned int IO_min_cap_leaves;}{Definition of the minimum number of entries in a leaf node.} \ccTypedef{const static unsigned int IO_page_size;}{Definition of the size of a page, that is the size of Data in a page.} \ccTypedef{const static bool headerextern;}{If \ccc{headerextern=true} then the header is stored in external memory. In this case the files can be used to rebuild the tree. Otherwise, if \ccc{headerextern=false} the header file of the tree is stored in internal memory.} \end{ccClass} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \subsection{Requirements for User Defined Input/Output Traits Classes} \label{userIO} The \ccc{R_tree} gets two Input/Output traits classes as template arguments. One is the interface to the database for the \ccc{Data} entries of the tree and the other one is the interface to the database in which the nodes of the tree are to be stored. We here describe the necessary functionality a user defined Input/Output class has to provide. \begin{ccClass}{IO_traits} \noindent {\bf Class: IO\_traits} \ccDefinition Defines a database for R-Tree nodes or leafs. The following functions are used by the R-Tree. \ccCreationVariable{R} \ccCreation \ccConstructor{IO_traits(unsigned int pagesize, char* name, int m = fstream::ate, int prot = filebuf::openprot);} {A database with name \ccc{name} has to be constructed. A page of the database has size \ccc{pagesize}.} \ccOperations \ccMethod{void close();}{Must close the database and give the allocated memory free.} \ccMethod{difference_type get_pos();}{A new reference position for a new page that will be inserted has to be returned.} \ccMethod{bool insert(difference_type pos, char **x);}{A page \ccc{x} with reference position \ccc{pos} has to be inserted in the database.} \ccMethod{bool update(difference_type pos, char** x);}{The page at reference position \ccc{pos} must be updated with x.} \ccMethod{bool get(difference_type pos, char **x);}{The page at reference position \ccc{pos} has to be written into \ccc{x}. \ccc{x} provides \ccc{pagesize} space.} \ccMethod{bool erase(difference_type pos);}{The page at position \ccc{pos} has to be erased. } \ccMethod{bool deleted(difference_type pos);}{If the page at position \ccc{pos} is in use, \ccc{true} has to be returned. Otherwise, \ccc{false} has to be returned.} \end{ccClass} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%