[Boost-commit] svn:boost r48186 - sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc

From: mariano.consoni_at_[hidden]
Date: 2008-08-17 20:42:55

Author: mconsoni
Date: 2008-08-17 20:42:54 EDT (Sun, 17 Aug 2008)
New Revision: 48186
URL: http://svn.boost.org/trac/boost/changeset/48186

Log:
- moru documentation.

Removed:
   sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/introduction.qbk
Text files modified: 
   sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/faq.qbk           |     4                                         
   sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/index_types.qbk   |     7 +-                                      
   sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/spatial_index.qbk |    30 ++++++--------                          
   sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/tutorials.qbk     |    81 +++++++++++++++++++++++++++++++++++++++ 
   4 files changed, 98 insertions(+), 24 deletions(-)

Modified: sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/faq.qbk
==============================================================================
--- sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/faq.qbk	(original)
+++ sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/faq.qbk	2008-08-17 20:42:54 EDT (Sun, 17 Aug 2008)
@@ -14,7 +14,7 @@
 Answer: There is no best index for every indexing problem, each one has its own 
 strenghts. In the "Performance comparison" section we show each index at work
 and we mark their own strenghts. As a rule of thumb you should use the rtree for
-large data sets with rare inserts/updates and the quadtree for 
-scenarios where insert/updates very frequent. This is motly because the rtree
+large data sets with few inserts/updates and the quadtree for 
+scenarios where insert/updates are very frequent. This is mostly because the rtree
 node spliting/joining algorithms are heavier than the simple quadree insertion
 algorithm.

Modified: sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/index_types.qbk
==============================================================================
--- sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/index_types.qbk	(original)
+++ sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/index_types.qbk	2008-08-17 20:42:54 EDT (Sun, 17 Aug 2008)
@@ -33,7 +33,7 @@
 
 [subsection:rtree Rtree]
 
-Inspired in database B-trees, this data structure splits the space in
+Inspired in database B-trees, this data structure divides the space in
 hierarchical areas called minimum bounding rectangles (MBR). Each node
 has a variable number of entries bounded by a minimum and a maximum.
 
@@ -43,6 +43,7 @@
 a child node.
 
 Different algorithms could be used to split the nodes when a node is 
-full balancing between performance and accuracy in finding the best
-node. In this implementation a linear algorithm is used.
+full, making trade-offs between performance and accuracy (related to 
+the performance the best node search algorithm). In 
+this implementation a linear algorithm is used.
 

Deleted: sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/introduction.qbk
==============================================================================
--- sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/introduction.qbk	2008-08-17 20:42:54 EDT (Sun, 17 Aug 2008)
+++ (empty file)
@@ -1,21 +0,0 @@
-[/ Boost.SpatialIndex - intro ]
-[/ Copyright 2008 Federico J. Fernandez ]
-[/ Distributed under the Boost Software License, Version 1.0. (See]
-[/ accompanying file LICENSE_1_0.txt or copy at ]
-[/ http://www.boost.org/LICENSE_1_0.txt) ]
-[/ See http://www.boost.org/ for latest version. ]
-
-[section:introduction Introduction]
-
-Spatial indexes are data structures optimized for spatial oriented queries. The
-classic index structures (i.e. a binary tree) aren't spatially enabled, they 
-have different ordering criteria but none of them relates to topological 
-properties.
-
-Bosot.SpatialIndex aims to implement spatial indexes as part of the Geometry 
-Library proposal that Barend Gehrels is preparing for Boost. Nowadays, the 
-library supports Quadtree and rTree indexes. Details of the strengths of 
-each one will be detailed afterwards.
-
-The scope of these structures is really wide, from collision detection for
-games to geometry indexing for GIS software.

Modified: sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/spatial_index.qbk
==============================================================================
--- sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/spatial_index.qbk	(original)
+++ sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/spatial_index.qbk	2008-08-17 20:42:54 EDT (Sun, 17 Aug 2008)
@@ -1,10 +1,10 @@
 
 [library Spatial Index
     [quickbook 1.4]
-    [version 0.01e-10]
+    [version 0.01]
     [authors [Fernandez, Federico J.]]
     [copyright 2008 Federico J. Fernandez]
-    [purpose Doing nothing.]
+    [purpose Structures for spatial indexing.]
     [license
         Distributed under the Boost Software License, Version 1.0.
         (See accompanying file LICENSE_1_0.txt or copy at
@@ -12,29 +12,25 @@
     ]
 ]
 
-Welcome to the Spatial Index!  One day, it will perhaps be called
-Boost.Spatial Index. Until then, feel free to use it to do nothing.
-
-[warning Spatial Index is not an official Boost library.]
-
 [section:introduction Introduction]
 
-User, this is Spatial Index.  Spatial Index, this is the user.  Be nice to each other.
-
-[section:start Getting Started]
-
-The Spatial Index is located in the spatial_index directory of the boost sandbox.
-
-
-You might also want to look at the [link spatial_index.reference reference].
+Spatial indexes are data structures optimized for spatial oriented queries. The
+classic index structures (i.e. a binary tree) aren't spatially enabled, they 
+have different ordering criteria but none of them relates to topological 
+properties.
+
+Bosot.SpatialIndex aims to implement spatial indexes as part of the Geometry 
+Library proposal that Barend Gehrels is preparing for Boost. Nowadays, the 
+library supports Quadtree and rTree indexes. Details of the strengths of 
+each one will be detailed afterwards.
 
+The scope of these structures is really wide, from collision detection for
+games to geometry indexing for GIS software.
 
 [endsect]
 
 [endsect]
 
-[xinclude spatial_index_doxygen.xml]
-
 [section:license License]
 
 Copyright 2008 Federico J. Fernandez.

Modified: sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/tutorials.qbk
==============================================================================
--- sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/tutorials.qbk	(original)
+++ sandbox/SOC/2008/spacial_indexing/libs/spatial_index/doc/tutorials.qbk	2008-08-17 20:42:54 EDT (Sun, 17 Aug 2008)
@@ -100,7 +100,7 @@
 q.remove(geometry::point_xy<double>(9.0,9.0));
 ``
 
-[section:tutorial1 Tutorial - rtree particularities]
+[section:tutorial2 Tutorial - rtree particularities]
 
 In this tutorial we want to show how could change the previous tutorial with
 the use of an rtree. As it's a different structure the creation parameters are
@@ -125,10 +125,87 @@
 Then the insertion method is overloaded to support geometry proposal's boxes:
 
 ``
-void insert(const geometry::box<Point> &e, const Value & v);
+hvoid insert(const geometry::box<Point> &e, const Value & v);
 ``
 
 A complete example showing the basic usage of the rtree could be found in
 test/simple_test_rtree.cpp.
 
+
+[section:tutorial3 Tutorial - Using your own point structure]
+
+As we have seen in the first tutorial, the data structure is
+a template parameter and we don't impose any requeriments over it, so it could be
+belong to any type. We have shown an example where an iterator to a STL
+container is used.
+
+As the title of this section suggests, it's also possible to use your own 
+point structure. We follow the approach used by the geometry library proposal.
+They define a point concept that your structure must fulfill to be able to be used
+with the library.
+
+The most important methods are the get<N> methods for each coordinate. You could
+easly get them inheriting from boost::tuple for example. Besides that an enum called
+"coordinate_count" should be declared setting the number of dimensions of the point.
+
+You also have to define a typedef defining the coordinate type. 
+
+Finally, there are some strategy traits that are used for the algorithms of the geometry
+library. For the Spatial Index it's ok to leave them as defaults because we don't use them,
+but if you want to use your point structure with the geometry library proposal you should
+do it.
+
+Let's see an example structure (taken from test/custom_point_test.cpp):
+
+``
+struct my_2d_point: boost::tuple < float, float >
+{
+  typedef float coordinate_type;
+  enum { coordinate_count = 2 };
+
+  my_2d_point(void)
+  {
+    get<0>() = 0.0;
+    get<1>() = 0.0;
+  }
+
+  my_2d_point(float x, float y)
+  {
+    get<0>() = x;
+    get<1>() = y;
+  }
+
+  bool operator<(const my_2d_point & o) const
+  {
+    return get<0> () <o. get <0> ();
+  }
+
+  // Because the geometry::point concept shares the "get" methods with 
+  // boost::tuple, no more methods are needed.
+};
+
+
+// point traits as in the geometry library proposal
+namespace geometry
+{
+  template <> 
+  struct strategy_traits < my_2d_point, my_2d_point >
+  {
+    typedef strategy::distance::pythagoras < my_2d_point, my_2d_point > 
+      point_distance;
+    typedef strategy::not_implemented point_segment_distance;
+    typedef strategy::not_implemented area;
+    typedef strategy::not_implemented within;
+    typedef strategy::not_implemented centroid;
+    typedef strategy::not_implemented envelope;
+  };
+
+  template <> struct wkt_traits < my_2d_point >
+  {
+    typedef impl::wkt::stream_point < my_2d_point > stream_type;
+  };
+}                               // namespace geometry
+``
+
+
 [endsect]