Complete Voronoi Map

AUTHORS

@@ -28,4 +28,5 @@ Boris Mansencal <[email protected]>
 Raphael Lenain <[email protected]>
 Johanna Delanoy <[email protected]>
 Phuc Ngo <[email protected]>
-J. Miguel Salazar <[email protected]>
+J. Miguel Salazar <[email protected]>
+Robin Lamy <[email protected]>

ChangeLog.md

@@ -40,6 +40,12 @@
  (Bertrand Kerautret, Phuc Ngo and David Coeurjolly
  [#1593](https:/DGtal-team/DGtal/pull/1593))
 
+- *Geometry*
+ - New VoronoiMapComplete class to store the full Voronoi map (with
+ all co-cycling sites (Robin Lamy, David Coeurjolly, Isabelle
+ Sivignon [#1605](https:/DGtal-team/DGtal/pull/1605))
+
+
 - *Build*
  - New cmake option (DGTAL_RANDOMIZED_TESTING_THRESHOLD) to set the
  (approximated) % of unit-tests to build and run for randomized

src/DGtal/doc/global.bib

@@ -598,6 +598,17 @@ @InProceedings{dcoeurjo_metric14
  url = {http://liris.cnrs.fr/publis/?id=6698}
 }
 
+@article{Couprie2007,
+ title={Discrete bisector function and Euclidean skeleton in 2D and 3D},
+ author={Couprie, Michel and Coeurjolly, David and Zrour, Rita},
+ journal={Image and Vision Computing},
+ volume={25},
+ number={10},
+ pages={1543--1556},
+ year={2007},
+ publisher={Elsevier}
+}
+
 
 @article{dcoeurjo_pami_RDMA,
  Month = {mar},

src/DGtal/geometry/doc/moduleVolumetric.dox

@@ -21,7 +21,7 @@ namespace DGtal {
 
 [TOC]
 
-@author David Coeurjolly, Roland Denis
+@author David Coeurjolly, Roland Denis, Robin Lamy (VoronoiComplete)
 
 This part of the manual describes the DGtal volumetric module. We
 focus here on separable process based volumetric analysis such as
@@ -102,7 +102,9 @@ similarly.
 output of the result is the intersection between the Voronoi diagram
 of exterior points with @f$ \mathbb{Z}^d @f$. Furthermore, along
 Voronoi faces (@e e.i. when two sites are equidistant), only one sites
-is considered when intersection with @f$ \mathbb{Z}^d @f$.
+is considered when intersection with @f$ \mathbb{Z}^d @f$. If you
+want the complete Voronoi map (i.e. h @f$ \mathcal{V}\cap\mathbb{Z}^d
+@f$, have a look to @ref vorocomplete.
 
 
 In DGtal, the class VoronoiMap implements such digital Vornoi map
@@ -210,6 +212,50 @@ new Voronoi map:
 @image html voronoimap-vorol8.png "Voronoi map for the l_8 metric."
 @image latex voronoimap-vorol8.png "Voronoi map for the l_8 metric."
 
+@section vorocomplete Complete Discrete Voronoi Map
+
+In this section, we describe the VoronoiMapComplete class that implements
+the complete Voronoi map with all co-cyclic points. More precisely if
+a grid point is equidistant to two sites, the two sites are reported
+in the VoronoiComplete map .
+
+This extension of the separable approach has been described in @cite Couprie2007 
+
+The overall algorithm is roughly the same
+(separable decomposition, each grid point is processed a constant
+amount of time), the only difference is that per grid point, we need
+to iterate over all co-cyclic sites obtained from the partial Voronoi
+map of the preceding dimensions. If the domain has no co-cycling
+sites, the asymptotic computational cost is exactly the same as
+VoronoiMap, if not, there is an extra factor that is a function of the
+number of co-cyclic points.
+
+The interface is exactly the same as the VoronoiMap, except that the
+output image is an image of `std::set<Point>` instead of an image of
+`Point`. As we rely on `std::set` as a per pixel container, and if
+@f$f@f$ denotes the number of co-cyclic sites at a point, the extra
+factor is in @f$ O(f \log f) @f$ (as insertion is expected to be done
+in logarithmic time for `std::set`). 
+
+
+@note Beside the extra computational cost due to the processing of
+co-cyclic sites, the VoronoiMapComplete class as a bigger constant
+factor due to the construction of the container. Indeed, as
+illustrated in testVoronoiMapComplete, creating a VoronoiMap on a
+256x256 image without any site takes 4ms, whereas the same size
+VoronoiMapComplete (still no sites) takes 118ms (on a MacPro). To be
+complete, when adding 5000 random sites, VoronoiMap takes 6.2ms in
+total, and 162ms for the VoronoiMapComplete (maximum number of
+co-cyclic sites = 4). The construction time should be amortized on
+larger domains.
+
+@note Associative containers with O(1) amortized insertion like
+`std::unordered_set` lead to higher construction time without a clear
+improvment on the overall performances.
+
+The VoronoiMapComplete class can also be applied on toroidal domains
+(see @ref toricVol).
+
 @section DTsec Distance Transformation
 
 As discussed earlier, the distance transformation is given by
@@ -301,13 +347,13 @@ ExactPredicateLpPowerSeparableMetric, see @ref moduleMetrics
 
 In some specific applications, toric domains and volumetric analysis
 of shapes in toric domains are crucial. Thanks to the separability
-property of VoronoiMap, PowerMap (and their associated wrappers
+property of VoronoiMap, VoronoiMapComplete, PowerMap (and their associated wrappers
 DistanceTransformation and ReverseDistanceTransformation), one can
 easily consider volumetric transformation in arbitrary dimension on
 toric domains @cite Coeurjo2008. Note that changing the periodicity
 property of the domain has no impact on the computational cost.
 
-More precisely, VoronoiMap and DistanceTransformation classes have
+More precisely, VoronoiMap, VoronoiMapComplete and DistanceTransformation classes have
 constructors allowing to specify periodicity information. In dimension
 @e d, such periodicity information is an array with @e d boolean flags
 where the i-th value is \c true if the i-th dimension of the space is

src/DGtal/geometry/doc/packageGeometry.dox

@@ -74,7 +74,7 @@ of arbitrary dimension, by the means of separable and incremental distance trans
 
 - Volumetric analysis
  - \ref moduleMetrics (David Coeurjolly)
- - \ref moduleVolumetric (David Coeurjolly, Roland Denis)
+ - \ref moduleVolumetric (David Coeurjolly, Roland Denis, Robin Lamy (VoronoiComplete))
  - \ref moduleFMM (Tristan Roussillon) 
  - \ref moduleDigitalConvexity (Jacques-Olivier Lachaud)
 

src/DGtal/geometry/volumes/distance/VoronoiMap.h

@@ -73,8 +73,8 @@ namespace DGtal
  *
  * Given a domain and a point predicate, an instance returns, for
  * each point in the domain, the closest point for which the
- * predicate if false. Following Computational Geometry
- * terminoliogy, points for which the predicate is false are "sites"
+ * predicate is false. Following Computational Geometry
+ * terminology, points for which the predicate is false are "sites"
  * for the Voronoi map construction. If a point is equi-distant to
  * two sites (e.g. if the digital point belong to a Voronoi cell
  * boundary in the Euclidean space), this Voronoi map construction

src/DGtal/geometry/volumes/distance/VoronoiMap.ih

@@ -29,11 +29,6 @@
 
 //////////////////////////////////////////////////////////////////////////////
 #include <cstdlib>
-
-#ifdef VERBOSE
-#include <boost/lexical_cast.hpp>
-#endif
-
 #include "DGtal/kernel/NumberTraits.h"
 
 //////////////////////////////////////////////////////////////////////////////
@@ -76,7 +71,7 @@ void
 DGtal::VoronoiMap<S,P, TSep, TImage>::computeOtherSteps ( const Dimension dim ) const
 {
 #ifdef VERBOSE
- std::string title = "VoronoiMap dimension " + boost::lexical_cast<std::string>( dim ) ;
+ std::string title = "VoronoiMap dimension " + std::to_string( dim ) ;
  trace.beginBlock ( title );
 #endif