MRPT  1.9.9
KmTree.h
Go to the documentation of this file.
1 /* +------------------------------------------------------------------------+
2  | Mobile Robot Programming Toolkit (MRPT) |
3  | https://www.mrpt.org/ |
4  | |
5  | Copyright (c) 2005-2020, Individual contributors, see AUTHORS file |
6  | See: https://www.mrpt.org/Authors - All rights reserved. |
7  | Released under BSD License. See: https://www.mrpt.org/License |
8  +------------------------------------------------------------------------+ */
9 // BEWARE: BETA VERSION
10 // --------------------
11 //
12 // A k-d tree that vastly speeds up an iteration of k-means (in any number of
13 // dimensions). The main
14 // idea for this data structure is from Kanungo/Mount. This is used internally
15 // by Kmeans.cpp, and
16 // will most likely not need to be used directly.
17 //
18 // The stucture works as follows:
19 // - All data points are placed into a tree where we choose child nodes by
20 // partitioning all data
21 // points along a plane parallel to the axis.
22 // - We maintain for each node, the bounding box of all data points stored at
23 // that node.
24 // - To do a k-means iteration, we need to assign points to clusters and
25 // calculate the sum and
26 // the number of points assigned to each cluster. For each node in the tree,
27 // we can rule out
28 // some cluster centers as being too far away from every single point in
29 // that bounding box.
30 // Once only one cluster is left, all points in the node can be assigned to
31 // that cluster in
32 // batch.
33 //
34 // Author: David Arthur (darthur@gmail.com), 2009
35 
36 #pragma once
37 
38 // Includes
39 #include "KmUtils.h"
40 
41 // KmTree class definition
42 class KmTree
43 {
44  public:
45  // Constructs a tree out of the given n data points living in R^d.
46  KmTree(int n, int d, Scalar* points);
47  ~KmTree();
48 
49  // Given k cluster centers, this runs a full k-means iterations, choosing
50  // the next set of
51  // centers and returning the cost function for this set of centers. If
52  // assignment is not null,
53  // it should be an array of size n that will be filled with the index of the
54  // cluster (0 - k-1)
55  // that each data point is assigned to. The new center values will overwrite
56  // the old ones.
57  Scalar DoKMeansStep(int k, Scalar* centers, int* assignment) const;
58 
59  // Choose k initial centers for k-means using the kmeans++ seeding
60  // procedure. The resulting
61  // centers are returned via the centers variable, which should be
62  // pre-allocated to size k*d.
63  // The cost of the initial clustering is returned.
64  Scalar SeedKMeansPlusPlus(int k, Scalar* centers) const;
65 
66  private:
67  struct Node
68  {
69  int num_points; // Number of points stored in this node
70  int first_point_index; // The smallest point index stored in this node
71  Scalar *median, *radius; // Bounding box center and half side-lengths
72  Scalar* sum; // Sum of the points stored in this node
73  Scalar opt_cost; // Min cost for putting all points in this node in 1
74  // cluster
75  Node *lower_node, *upper_node; // Child nodes
76  mutable int kmpp_cluster_index; // The cluster these points are
77  // assigned to or -1 if variable
78  };
79 
80  // Helper functions for constructor
82  Scalar* points, int first_index, int last_index, char** next_node_data);
83  Scalar GetNodeCost(const Node* node, Scalar* center) const;
84 
85  // Helper functions for DoKMeans step
87  const Node* node, int k, int* candidates, Scalar* centers, Scalar* sums,
88  int* counts, int* assignment) const;
89  bool ShouldBePruned(
90  Scalar* box_median, Scalar* box_radius, Scalar* centers, int best_index,
91  int test_index) const;
92 
93  // Helper functions for SeedKMeansPlusPlus
94  void SeedKmppSetClusterIndex(const Node* node, int index) const;
96  const Node* node, int new_cluster, Scalar* centers,
97  Scalar* dist_sq) const;
98 
99  int n_, d_;
102  char* node_data_;
104 };
double Scalar
Definition: KmUtils.h:43
Scalar * median
Definition: KmTree.h:71
int kmpp_cluster_index
Definition: KmTree.h:76
KmTree(int n, int d, Scalar *points)
Definition: KmTree.cpp:19
Scalar * radius
Definition: KmTree.h:71
bool ShouldBePruned(Scalar *box_median, Scalar *box_radius, Scalar *centers, int best_index, int test_index) const
Definition: KmTree.cpp:325
Scalar GetNodeCost(const Node *node, Scalar *center) const
Definition: KmTree.cpp:231
int n_
Definition: KmTree.h:99
Node * lower_node
Definition: KmTree.h:75
int * point_indices_
Definition: KmTree.h:103
Scalar opt_cost
Definition: KmTree.h:73
Scalar * sum
Definition: KmTree.h:72
Scalar DoKMeansStep(int k, Scalar *centers, int *assignment) const
Definition: KmTree.cpp:58
int num_points
Definition: KmTree.h:69
int d_
Definition: KmTree.h:99
Definition: KmTree.h:42
Scalar SeedKmppUpdateAssignment(const Node *node, int new_cluster, Scalar *centers, Scalar *dist_sq) const
Definition: KmTree.cpp:402
Scalar DoKMeansStepAtNode(const Node *node, int k, int *candidates, Scalar *centers, Scalar *sums, int *counts, int *assignment) const
Definition: KmTree.cpp:252
Scalar SeedKMeansPlusPlus(int k, Scalar *centers) const
Definition: KmTree.cpp:346
~KmTree()
Definition: KmTree.cpp:52
Node * BuildNodes(Scalar *points, int first_index, int last_index, char **next_node_data)
Definition: KmTree.cpp:106
int first_point_index
Definition: KmTree.h:70
char * node_data_
Definition: KmTree.h:102
void SeedKmppSetClusterIndex(const Node *node, int index) const
Definition: KmTree.cpp:392
Scalar * points_
Definition: KmTree.h:100
Node * top_node_
Definition: KmTree.h:101
Node * upper_node
Definition: KmTree.h:75



Page generated by Doxygen 1.8.14 for MRPT 1.9.9 Git: c7a3bec24 Sun Mar 29 18:33:13 2020 +0200 at dom mar 29 18:50:38 CEST 2020