1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkIterativeClosestPointTransform.h
5 
6   Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
7   All rights reserved.
8   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
9 
10      This software is distributed WITHOUT ANY WARRANTY; without even
11      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
12      PURPOSE.  See the above copyright notice for more information.
13 
14 =========================================================================*/
15 
16 // .NAME vtkIterativeClosestPointTransform - Implementation of the ICP algorithm.
17 // .SECTION Description
18 // Match two surfaces using the iterative closest point (ICP) algorithm.
19 // The core of the algorithm is to match each vertex in one surface with
20 // the closest surface point on the other, then apply the transformation
21 // that modify one surface to best match the other (in a least square sense).
22 // This has to be iterated to get proper convergence of the surfaces.
23 // .SECTION Note
24 // Use vtkTransformPolyDataFilter to apply the resulting ICP transform to
25 // your data. You might also set it to your actor's user transform.
26 // .SECTION Note
27 // This class makes use of vtkLandmarkTransform internally to compute the
28 // best fit. Use the GetLandmarkTransform member to get a pointer to that
29 // transform and set its parameters. You might, for example, constrain the
30 // number of degrees of freedom of the solution (i.e. rigid body, similarity,
31 // etc.) by checking the vtkLandmarkTransform documentation for its SetMode
32 // member.
33 // .SECTION see also
34 // vtkLandmarkTransform
35 
36 
37 #ifndef vtkIterativeClosestPointTransform_h
38 #define vtkIterativeClosestPointTransform_h
39 
40 #include "vtkCommonDataModelModule.h" // For export macro
41 #include "vtkLinearTransform.h"
42 
43 #define VTK_ICP_MODE_RMS 0
44 #define VTK_ICP_MODE_AV 1
45 
46 class vtkCellLocator;
47 class vtkLandmarkTransform;
48 class vtkDataSet;
49 
50 class VTKCOMMONDATAMODEL_EXPORT vtkIterativeClosestPointTransform : public vtkLinearTransform
51 {
52 public:
53   static vtkIterativeClosestPointTransform *New();
54   vtkTypeMacro(vtkIterativeClosestPointTransform,vtkLinearTransform);
55   void PrintSelf(ostream& os, vtkIndent indent);
56 
57   // Description:
58   // Specify the source and target data sets.
59   void SetSource(vtkDataSet *source);
60   void SetTarget(vtkDataSet *target);
61   vtkGetObjectMacro(Source, vtkDataSet);
62   vtkGetObjectMacro(Target, vtkDataSet);
63 
64   // Description:
65   // Set/Get a spatial locator for speeding up the search process.
66   // An instance of vtkCellLocator is used by default.
67   void SetLocator(vtkCellLocator *locator);
68   vtkGetObjectMacro(Locator,vtkCellLocator);
69 
70   // Description:
71   // Set/Get the  maximum number of iterations. Default is 50.
72   vtkSetMacro(MaximumNumberOfIterations, int);
73   vtkGetMacro(MaximumNumberOfIterations, int);
74 
75   // Description:
76   // Get the number of iterations since the last update
77   vtkGetMacro(NumberOfIterations, int);
78 
79   // Description:
80   // Force the algorithm to check the mean distance between two iterations.
81   // Default is Off.
82   vtkSetMacro(CheckMeanDistance, int);
83   vtkGetMacro(CheckMeanDistance, int);
84   vtkBooleanMacro(CheckMeanDistance, int);
85 
86   // Description:
87   // Specify the mean distance mode. This mode expresses how the mean
88   // distance is computed. The RMS mode is the square root of the average
89   // of the sum of squares of the closest point distances. The Absolute
90   // Value mode is the mean of the sum of absolute values of the closest
91   // point distances. The default is VTK_ICP_MODE_RMS
92   vtkSetClampMacro(MeanDistanceMode,int,
93                    VTK_ICP_MODE_RMS,VTK_ICP_MODE_AV);
94   vtkGetMacro(MeanDistanceMode,int);
SetMeanDistanceModeToRMS()95   void SetMeanDistanceModeToRMS()
96     {this->SetMeanDistanceMode(VTK_ICP_MODE_RMS);}
SetMeanDistanceModeToAbsoluteValue()97   void SetMeanDistanceModeToAbsoluteValue()
98     {this->SetMeanDistanceMode(VTK_ICP_MODE_AV);}
99   const char *GetMeanDistanceModeAsString();
100 
101   // Description:
102   // Set/Get the maximum mean distance between two iteration. If the mean
103   // distance is lower than this, the convergence stops. The default
104   // is 0.01.
105   vtkSetMacro(MaximumMeanDistance, double);
106   vtkGetMacro(MaximumMeanDistance, double);
107 
108   // Description:
109   // Get the mean distance between the last two iterations.
110   vtkGetMacro(MeanDistance, double);
111 
112   // Description:
113   // Set/Get the maximum number of landmarks sampled in your dataset.
114   // If your dataset is dense, then you will typically not need all the
115   // points to compute the ICP transform. The default is 200.
116   vtkSetMacro(MaximumNumberOfLandmarks, int);
117   vtkGetMacro(MaximumNumberOfLandmarks, int);
118 
119   // Description:
120   // Starts the process by translating source centroid to target centroid.
121   // The default is Off.
122   vtkSetMacro(StartByMatchingCentroids, int);
123   vtkGetMacro(StartByMatchingCentroids, int);
124   vtkBooleanMacro(StartByMatchingCentroids, int);
125 
126   // Description:
127   // Get the internal landmark transform. Use it to constrain the number of
128   // degrees of freedom of the solution (i.e. rigid body, similarity, etc.).
129   vtkGetObjectMacro(LandmarkTransform,vtkLandmarkTransform);
130 
131   // Description:
132   // Invert the transformation.  This is done by switching the
133   // source and target.
134   void Inverse();
135 
136   // Description:
137   // Make another transform of the same type.
138   vtkAbstractTransform *MakeTransform();
139 
140 protected:
141 
142   // Description:
143   // Release source and target
144   void ReleaseSource(void);
145   void ReleaseTarget(void);
146 
147   // Description:
148   // Release locator
149   void ReleaseLocator(void);
150 
151   // Description:
152   // Create default locator. Used to create one when none is specified.
153   void CreateDefaultLocator(void);
154 
155   // Description:
156   // Get the MTime of this object also considering the locator.
157   unsigned long int GetMTime();
158 
159   vtkIterativeClosestPointTransform();
160   ~vtkIterativeClosestPointTransform();
161 
162   void InternalUpdate();
163 
164   // Description:
165   // This method does no type checking, use DeepCopy instead.
166   void InternalDeepCopy(vtkAbstractTransform *transform);
167 
168   vtkDataSet* Source;
169   vtkDataSet* Target;
170   vtkCellLocator *Locator;
171   int MaximumNumberOfIterations;
172   int CheckMeanDistance;
173   int MeanDistanceMode;
174   double MaximumMeanDistance;
175   int MaximumNumberOfLandmarks;
176   int StartByMatchingCentroids;
177 
178   int NumberOfIterations;
179   double MeanDistance;
180   vtkLandmarkTransform *LandmarkTransform;
181 private:
182   vtkIterativeClosestPointTransform(const vtkIterativeClosestPointTransform&);  // Not implemented.
183   void operator=(const vtkIterativeClosestPointTransform&);  // Not implemented.
184 };
185 
186 #endif
187