Documentation of clustering code.

TULIP/src/lu/list/itis/dkd/tui/feature/cluster/ClusterManager.java

@@ -78,6 +78,55 @@ public class ClusterManager<P extends Positionable> {
     // ***************************************************************************
     // ---------------------------------------------------------------------------
 
+    private boolean cluster(List<P> candidates, List<P> retained, List<P> coalesced) {
+
+        boolean clusterDetected = false;
+
+        // Iterate over all candidates.
+        for (P candidate : candidates) {
+            // Check whether candidate is indeed clusterable and has not already been
+            // coalesced into a cluster.
+
+            if ((candidate instanceof Clusterable) && !coalesced.contains(candidate)) {
+
+                // Try to find items within a specific radius.
+
+                List<P> coalescing = kdTree.findNearest(candidate, radius);
+
+                // If there were items within that zone, than we the candidate will be
+                // a cluster, representing the matching items.
+
+                boolean isClustered = (!coalescing.isEmpty());
+
+                // However, since we don't rebuild the kdTree for performance reasons
+                // on each iteration, the tree will always hold to the totality of
+                // available items. We thus have to remove previously coalesced items
+                // in order to find out whether we're in the presence of a new cluster
+                // or not.
+
+                coalescing.removeAll(coalesced);
+                clusterDetected |= (!coalescing.isEmpty());
+
+                // Add remaining coalescing items to list of already coalesced items
+                // and make sure none of them remains in the retained list.
+
+                if (isClustered) {
+                    coalesced.addAll(coalescing);
+                    retained.removeAll(coalescing);
+                }
+
+                // Last but not least, set the candidates' clustered flag and add
+                // it to the list of retained items.
+
+                ((Clusterable) candidate).setClustered(isClustered);
+                if (!retained.contains(candidate)) {
+                    retained.add(candidate);
+                }
+            }
+        }
+        return clusterDetected;
+    }
+
     // ---------------------------------------------------------------------------
     // ***************************************************************************
     // * Class Body
@@ -133,27 +182,7 @@ public class ClusterManager<P extends Positionable> {
         int iterations = 0;
 
         do {
-            clusterDetected = false;
-
-            for (P candidate : candidates) {
-                if ((candidate instanceof Clusterable) && !coalesced.contains(candidate)) {
-                    List<P> coalescing = kdTree.findNearest(candidate, radius);
-                    boolean isClustered = (!coalescing.isEmpty());
-
-                    coalescing.removeAll(coalesced);
-                    clusterDetected |= (!coalescing.isEmpty());
-
-                    if (isClustered) {
-                        coalesced.addAll(coalescing);
-                        retained.removeAll(coalescing);
-                    }
-                    ((Clusterable) candidate).setClustered(isClustered);
-                    if (!retained.contains(candidate)) {
-                        retained.add(candidate);
-                    }
-                }
-            }
-
+            clusterDetected = this.cluster(candidates, retained, coalesced);
             candidates.clear();
             candidates.addAll(retained);
             iterations++;
@@ -162,7 +191,7 @@ public class ClusterManager<P extends Positionable> {
         synchronized (clustered) {
             clustered.clear();
             clustered.addAll(retained);
-            LOGGER.info("Clustering completed in {} iteration(s)! {} Marker(s) remaining!", iterations, clustered.size());
+            LOGGER.info("Clustering completed in {} iteration(s)! {} Marker(s) remaining!", iterations, clustered.size()); //$NON-NLS-1$
         }
     }