updating the doc for the hilbert sort on the sphere

Spatial_sorting/doc/Spatial_sorting/CGAL/Hilbert_sort_on_sphere_3.h

@@ -0,0 +1,41 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgSpatialSortingFunctionObjects
+
+The function object `Hilbert_sort_on_sphere_3` sorts iterator ranges of 
+`Traits::Point_3` along a Hilbert curve on the unit sphere. Actually, it approximates a Hilbert curve on
+the sphere by a Hilbert curve on a cube with faces at \f$x, y, z = \pm 1/\sqrt{3}\f$. For each face of that cube, it calls an appropriate
+version of `Hilbert_sort_2` which sorts a subset of the iterator range.
+`Hilbert_sort_2` in each face is called with the median or the middle policy depending on the `PolicyTag`.
+
+\tparam Traits must be a model for `SpatialSortingTraits_3`. 
+
+*/
+template< typename Traits, typename PolicyTag >
+class Hilbert_sort_on_sphere_3 {
+public:
+
+/// \name Creation 
+/// @{
+
+/*!
+constructs an instance with `traits` as traits class instance. 
+*/ 
+Hilbert_sort_on_sphere_3(const Traits &traits = Traits()); 
+
+/// @} 
+
+/// \name Operations 
+/// @{
+
+/*!
+sorts the range `[begin, end)`. 
+\tparam RandomAccessIterator must be an iterator with value type `Traits::Point_3`. 
+*/ 
+template <class RandomAccessIterator> void operator() (RandomAccessIterator begin, RandomAccessIterator end) const; 
+
+/// @}
+
+}; /* end Hilbert_sort_on_sphere_3 */
+} /* end namespace CGAL */

Spatial_sorting/doc/Spatial_sorting/CGAL/hilbert_sort_on_sphere.h

@@ -0,0 +1,39 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgSpatialSortingFunctions
+
+The function `hilbert_sort_on_sphere()` sorts an iterator range of points that are supposed to be close to a unit sphere
+along a Hilbert curve on the unit sphere. Actually, it approximates a Hilbert curve on
+the sphere by a Hilbert curve on a cube.
+
+sorts the range `[begin, end)` in place. 
+
+The default traits class `Default_traits` is the kernel in which the type 
+`std::iterator_traits<RandomAccessIterator>::%value_type` is defined. 
+The default policy is `Hilbert_sort_median_policy()` and the 
+other option is `Hilbert_sort_middle_policy()`. 
+
+\cgalHeading{Requirements}
+
+<OL> 
+<LI>`std::iterator_traits<RandomAccessIterator>::%value_type` is convertible to 
+`Traits::Point_3`. 
+<LI>`Traits` is a model for concept `SpatialSortingTraits_3`. 
+</OL> 
+
+\cgalHeading{Implementation}
+
+Creates an instance of `Hilbert_sort_on_sphere<Traits, PolicyTag>`,
+and calls its `operator()`. 
+
+*/
+template <class RandomAccessIterator, class Traits, class PolicyTag>
+void
+hilbert_sort_on_sphere( RandomAccessIterator begin,
+RandomAccessIterator end,
+const Traits& traits = Default_traits,
+PolicyTag policy = Default_policy);
+
+} /* namespace CGAL */
+

Spatial_sorting/doc/Spatial_sorting/CGAL/spatial_sort_on_sphere.h

@@ -0,0 +1,55 @@
+namespace CGAL {
+
+/*!
+\ingroup PkgSpatialSortingFunctions
+
+The function `spatial_sort_on_sphere()` sorts an iterator range of points in a way that 
+improves space locality. Two points close in the order will be close 
+on the sphere, and two points close on the sphere will have a high probability 
+of being close in the order. 
+
+sorts the range `[begin, end)` in place. 
+
+The default traits class `Default_traits` is the kernel in which the type 
+`std::iterator_traits<RandomAccessIterator>::%value_type` is defined. 
+
+The default policy is `Hilbert_sort_median_policy()` and the 
+other option is `Hilbert_sort_middle_policy()`. 
+
+\cgalHeading{Requirements}
+
+<OL> 
+<LI>`std::iterator_traits<RandomAccessIterator>::%value_type` is convertible to 
+`Traits::Point_3`. 
+<LI>`Traits` is a model for concept `SpatialSortingTraits_3`. 
+</OL> 
+
+\cgalHeading{Implementation}
+
+Creates an instance of `Multiscale_sort<Hilbert_sort>` 
+where `Hilbert_sort` is an Hilbert sorting object, 
+and calls its `operator()`. 
+
+The `threshold_hilbert` is the minimal size of a point set to be 
+subdivided recursively during Hilbert sorting, otherwise random order is used. 
+The `threshold_multiscale` value is the minimal size for a sample to 
+call Hilbert sort, otherwise random order is used. 
+The `ratio` value is used to split the original set in two subsets, 
+spatial sort is applied on the first subset of size 
+`ratio` 
+times the original size of the set, Hilbert sort is applied on the 
+second subset. 
+
+*/
+template <class RandomAccessIterator, class Traits, class PolicyTag>
+void
+spatial_sort( RandomAccessIterator begin,
+RandomAccessIterator end,
+const Traits& traits = Default_traits,
+PolicyTag policy = Default_policy,
+std::ptrdiff_t threshold_hilbert=default,
+std::ptrdiff_t threshold_multiscale=default,
+double ratio=default);
+
+} /* namespace CGAL */
+

Spatial_sorting/doc/Spatial_sorting/Concepts/SpatialSortingTraits_3.h

@@ -3,7 +3,7 @@
 \ingroup PkgSpatialSortingConcepts
 \cgalConcept
 
-All 3D spatial sorting algorithms provided in \cgal are parameterized 
+All 3D spatial sorting algorithms, including sorting on the sphere, provided in \cgal are parameterized 
 by a traits class `Traits`, which defines the 
 primitives (objects and predicates) that the sorting algorithms use. 
 `SpatialSortingTraits_3` defines the complete set of primitives required in these 

Spatial_sorting/doc/Spatial_sorting/PackageDescription.txt

@@ -23,7 +23,7 @@
 \cgalPkgPicture{hilbert.png}
 \cgalPkgSummaryBegin
 \cgalPkgAuthors{Christophe Delage and Olivier Devillers}
-\cgalPkgDesc{This package provides functions for sorting geometric objects in two, three and higher dimensions, in order to improve efficiency of incremental geometric algorithms.}
+\cgalPkgDesc{This package provides functions for sorting geometric objects in two, three and higher dimensions, including on a sphere, in order to improve efficiency of incremental geometric algorithms.}
 \cgalPkgManuals{Chapter_Spatial_Sorting,PkgSpatialSorting}
 \cgalPkgSummaryEnd
 \cgalPkgShortInfoBegin
@@ -37,12 +37,15 @@
 
 ## Functions ##
 - `CGAL::spatial_sort()`
+- `CGAL::spatial_sort_on_sphere()`
 - `CGAL::hilbert_sort()`
+- `CGAL::hilbert_sort_on_sphere()`
 
 ## Function Objects ##
 - `CGAL::Multiscale_sort<Sort>`
 - `CGAL::Hilbert_sort_2<Traits, PolicyTag>`
 - `CGAL::Hilbert_sort_3<Traits, PolicyTag>`
+- `CGAL::Hilbert_sort_on_sphere_3<Traits, PolicyTag>`
 - `CGAL::Hilbert_sort_d<Traits, PolicyTag>`
 
 ## Traits classes ##

Spatial_sorting/doc/Spatial_sorting/Spatial_sorting.txt

@@ -73,8 +73,8 @@ We also consider space filling curves on the unit sphere.
 Actually, we approximate a space filling curve on
 the unit sphere by a space filling curve on a cube (with faces at \f$x, y, z = \pm 1/\sqrt{3}\f$). 
 Roughly speaking, we split the original set of points in six disjoint subsets: for each face \f$f\f$ of the cube we consider points that are above \f$f\f$ as belonging
-to one of such subsets. And then we basically use the 2D Hilbert sort as explained above for each subset, following the correct axis orientation;
-see \cgalFigureRef{Spatial_sorting_fig_Faces_orientations}.
+to one of such subsets. And then we basically use the 2D Hilbert sort as explained above for the projection of the points in each subset on its corresponding face of the cube.
+The axes orientation on each face is chosen so that the space filling curve covers the whole cube without any jump; see \cgalFigureRef{Spatial_sorting_fig_Faces_orientations}.
 
 \cgalFigureBegin{Spatial_sorting_fig_Faces_orientations,HilbertOnSphere.png}
 A 2D Hilbert sort for each face of the cube

Spatial_sorting/doc/Spatial_sorting/examples.txt

@@ -2,8 +2,10 @@
 \example Spatial_sorting/hilbert.cpp
 \example Spatial_sorting/hilbert_policies.cpp
 \example Spatial_sorting/small_example_delaunay_2.cpp
+\example Spatial_sorting/hilbert_sort_on_sphere.cpp
 \example Spatial_sorting/myPoint.cpp
 \example Spatial_sorting/sp_sort_using_property_map_2.cpp
 \example Spatial_sorting/sp_sort_using_property_map_3.cpp
 \example Spatial_sorting/sp_sort_using_property_map_d.cpp
+\example Spatial_sorting/spherical_spatial_sort.cpp
 */