1 /*========================================================================= 2 3 Program: Visualization Toolkit 4 Module: vtkPointInterpolator.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 * @class vtkPointInterpolator 17 * @brief interpolate over point cloud using various kernels 18 * 19 * 20 * vtkPointInterpolator probes a point cloud Pc (the filter Source) with a 21 * set of points P (the filter Input), interpolating the data values from Pc 22 * onto P. Note however that the descriptive phrase "point cloud" is a 23 * misnomer: Pc can be represented by any vtkDataSet type, with the points of 24 * the dataset forming Pc. Similarly, the output P can also be represented by 25 * any vtkDataSet type; and the topology/geometry structure of P is passed 26 * through to the output along with the newly interpolated arrays. 27 * 28 * A key input to this filter is the specification of the interpolation 29 * kernel, and the parameters which control the associated interpolation 30 * process. Interpolation kernels include Voronoi, Gaussian, Shepard, and SPH 31 * (smoothed particle hydrodynamics), with additional kernels to be added in 32 * the future. 33 * 34 * An overview of the algorithm is as follows. For each p from P, Np "close" 35 * points to p are found. (The meaning of what is "close" can be specified as 36 * either the N closest points, or all points within a given radius Rp. This 37 * depends on how the kernel is defined.) Once the Np close points are found, 38 * then the interpolation kernel is applied to compute new data values 39 * located on p. Note that for reasonable performance, finding the Np closest 40 * points requires a point locator. The locator may be specified as input to 41 * the algorithm. (By default, a vtkStaticPointLocator is used because 42 * generally it is much faster to build, delete, and search with. However, 43 * with highly non-uniform point distributions, octree- or kd-tree based 44 * locators may perform better.) 45 * 46 * @warning 47 * This class has been threaded with vtkSMPTools. Using TBB or other 48 * non-sequential type (set in the CMake variable 49 * VTK_SMP_IMPLEMENTATION_TYPE) may improve performance significantly. 50 * 51 * @warning 52 * For widely spaced points in Pc, or when p is located outside the bounding 53 * region of Pc, the interpolation may behave badly and the interpolation 54 * process will adapt as necessary to produce output. For example, if the N 55 * closest points within R are requested to interpolate p, if N=0 then the 56 * interpolation will switch to a different strategy (which can be controlled 57 * as in the NullPointsStrategy). 58 * 59 * @sa 60 * vtkPointInterpolator2D vtkProbeFilter vtkGaussianSplatter 61 * vtkCheckerboardSplatter vtkShepardMethod vtkVoronoiKernel vtkShepardKernel 62 * vtkGaussianKernel vtkSPHKernel 63 */ 64 65 #ifndef vtkPointInterpolator_h 66 #define vtkPointInterpolator_h 67 68 #include "vtkFiltersPointsModule.h" // For export macro 69 #include "vtkDataSetAlgorithm.h" 70 #include "vtkStdString.h" // For vtkStdString ivars 71 #include <vector> //For STL vector 72 73 class vtkAbstractPointLocator; 74 class vtkIdList; 75 class vtkDoubleArray; 76 class vtkInterpolationKernel; 77 class vtkCharArray; 78 79 80 class VTKFILTERSPOINTS_EXPORT vtkPointInterpolator : public vtkDataSetAlgorithm 81 { 82 public: 83 //@{ 84 /** 85 * Standard methods for instantiating, obtaining type information, and 86 * printing. 87 */ 88 static vtkPointInterpolator *New(); 89 vtkTypeMacro(vtkPointInterpolator,vtkDataSetAlgorithm); 90 void PrintSelf(ostream& os, vtkIndent indent) override; 91 //@} 92 93 //@{ 94 /** 95 * Specify the dataset Pc that will be probed by the input points P. The 96 * Input P defines the dataset structure (the points and cells) for the 97 * output, while the Source Pc is probed (interpolated) to generate the 98 * scalars, vectors, etc. for the output points based on the point 99 * locations. 100 */ 101 void SetSourceData(vtkDataObject *source); 102 vtkDataObject *GetSource(); 103 //@} 104 105 /** 106 * Specify the dataset Pc that will be probed by the input points P. The 107 * Input P defines the structure (the points and cells) for the output, 108 * while the Source Pc is probed (interpolated) to generate the scalars, 109 * vectors, etc. for the output points based on the point locations. 110 */ 111 void SetSourceConnection(vtkAlgorithmOutput* algOutput); 112 113 //@{ 114 /** 115 * Specify a point locator. By default a vtkStaticPointLocator is 116 * used. The locator performs efficient searches to locate near a 117 * specified interpolation position. 118 */ 119 void SetLocator(vtkAbstractPointLocator *locator); 120 vtkGetObjectMacro(Locator,vtkAbstractPointLocator); 121 //@} 122 123 //@{ 124 /** 125 * Specify an interpolation kernel. By default a vtkLinearKernel is used 126 * (i.e., linear combination of closest points). The interpolation kernel 127 * changes the basis of the interpolation. 128 */ 129 void SetKernel(vtkInterpolationKernel *kernel); 130 vtkGetObjectMacro(Kernel,vtkInterpolationKernel); 131 //@} 132 133 enum Strategy 134 { 135 MASK_POINTS=0, 136 NULL_VALUE=1, 137 CLOSEST_POINT=2 138 }; 139 140 //@{ 141 /** 142 * Specify a strategy to use when encountering a "null" point during the 143 * interpolation process. Null points occur when the local neighborhood (of 144 * nearby points to interpolate from) is empty. If the strategy is set to 145 * MaskPoints, then an output array is created that marks points as being 146 * valid (=1) or null (invalid =0) (and the NullValue is set as well). If 147 * the strategy is set to NullValue (this is the default), then the output 148 * data value(s) are set to the NullPoint value (specified in the output 149 * point data). Finally, the strategy ClosestPoint is to simply use the 150 * closest point to perform the interpolation. 151 */ 152 vtkSetMacro(NullPointsStrategy,int); 153 vtkGetMacro(NullPointsStrategy,int); SetNullPointsStrategyToMaskPoints()154 void SetNullPointsStrategyToMaskPoints() 155 { this->SetNullPointsStrategy(MASK_POINTS); } SetNullPointsStrategyToNullValue()156 void SetNullPointsStrategyToNullValue() 157 { this->SetNullPointsStrategy(NULL_VALUE); } SetNullPointsStrategyToClosestPoint()158 void SetNullPointsStrategyToClosestPoint() 159 { this->SetNullPointsStrategy(CLOSEST_POINT); } 160 //@} 161 162 //@{ 163 /** 164 * If the NullPointsStrategy == MASK_POINTS, then an array is generated for 165 * each input point. This vtkCharArray is placed into the output of the filter, 166 * with a non-zero value for a valid point, and zero otherwise. The name of 167 * this masking array is specified here. 168 */ 169 vtkSetMacro(ValidPointsMaskArrayName, vtkStdString); 170 vtkGetMacro(ValidPointsMaskArrayName, vtkStdString); 171 //@} 172 173 //@{ 174 /** 175 * Specify the null point value. When a null point is encountered then all 176 * components of each null tuple are set to this value. By default the 177 * null value is set to zero. 178 */ 179 vtkSetMacro(NullValue,double); 180 vtkGetMacro(NullValue,double); 181 //@} 182 183 //@{ 184 /** 185 * Adds an array to the list of arrays which are to be excluded from the 186 * interpolation process. 187 */ AddExcludedArray(const vtkStdString & excludedArray)188 void AddExcludedArray(const vtkStdString &excludedArray) 189 { 190 this->ExcludedArrays.push_back(excludedArray); 191 this->Modified(); 192 } 193 //@} 194 195 //@{ 196 /** 197 * Clears the contents of excluded array list. 198 */ ClearExcludedArrays()199 void ClearExcludedArrays() 200 { 201 this->ExcludedArrays.clear(); 202 this->Modified(); 203 } 204 //@} 205 206 /** 207 * Return the number of excluded arrays. 208 */ GetNumberOfExcludedArrays()209 int GetNumberOfExcludedArrays() 210 {return static_cast<int>(this->ExcludedArrays.size());} 211 212 //@{ 213 /** 214 * Return the name of the ith excluded array. 215 */ GetExcludedArray(int i)216 const char* GetExcludedArray(int i) 217 { 218 if ( i < 0 || i >= static_cast<int>(this->ExcludedArrays.size()) ) 219 { 220 return nullptr; 221 } 222 return this->ExcludedArrays[i].c_str(); 223 } 224 //@} 225 226 //@{ 227 /** 228 * If enabled, then input arrays that are non-real types (i.e., not float 229 * or double) are promoted to float type on output. This is because the 230 * interpolation process may not be well behaved when integral types are 231 * combined using interpolation weights. 232 */ 233 vtkSetMacro(PromoteOutputArrays, bool); 234 vtkBooleanMacro(PromoteOutputArrays, bool); 235 vtkGetMacro(PromoteOutputArrays, bool); 236 //@} 237 238 //@{ 239 /** 240 * Indicate whether to shallow copy the input point data arrays to the 241 * output. On by default. 242 */ 243 vtkSetMacro(PassPointArrays, bool); 244 vtkBooleanMacro(PassPointArrays, bool); 245 vtkGetMacro(PassPointArrays, bool); 246 //@} 247 248 //@{ 249 /** 250 * Indicate whether to shallow copy the input cell data arrays to the 251 * output. On by default. 252 */ 253 vtkSetMacro(PassCellArrays, bool); 254 vtkBooleanMacro(PassCellArrays, bool); 255 vtkGetMacro(PassCellArrays, bool); 256 //@} 257 258 //@{ 259 /** 260 * Indicate whether to pass the field-data arrays from the input to the 261 * output. On by default. 262 */ 263 vtkSetMacro(PassFieldArrays, bool); 264 vtkBooleanMacro(PassFieldArrays, bool); 265 vtkGetMacro(PassFieldArrays, bool); 266 //@} 267 268 /** 269 * Get the MTime of this object also considering the locator and kernel. 270 */ 271 vtkMTimeType GetMTime() override; 272 273 protected: 274 vtkPointInterpolator(); 275 ~vtkPointInterpolator() override; 276 277 vtkAbstractPointLocator *Locator; 278 vtkInterpolationKernel *Kernel; 279 280 int NullPointsStrategy; 281 double NullValue; 282 vtkStdString ValidPointsMaskArrayName; 283 vtkCharArray *ValidPointsMask; 284 285 std::vector<vtkStdString> ExcludedArrays; 286 287 bool PromoteOutputArrays; 288 289 bool PassCellArrays; 290 bool PassPointArrays; 291 bool PassFieldArrays; 292 293 int RequestData(vtkInformation *, vtkInformationVector **, 294 vtkInformationVector *) override; 295 int RequestInformation(vtkInformation *, vtkInformationVector **, 296 vtkInformationVector *) override; 297 int RequestUpdateExtent(vtkInformation *, vtkInformationVector **, 298 vtkInformationVector *) override; 299 300 /** 301 * Virtual for specialized subclass(es) 302 */ 303 virtual void Probe(vtkDataSet *input, vtkDataSet *source, vtkDataSet *output); 304 305 /** 306 * Call at end of RequestData() to pass attribute data respecting the 307 * PassCellArrays, PassPointArrays, PassFieldArrays flags. 308 */ 309 virtual void PassAttributeData( 310 vtkDataSet* input, vtkDataObject* source, vtkDataSet* output); 311 312 /** 313 * Internal method to extract image metadata 314 */ 315 void ExtractImageDescription(vtkImageData *input, int dims[3], 316 double origin[3], double spacing[3]); 317 318 private: 319 vtkPointInterpolator(const vtkPointInterpolator&) = delete; 320 void operator=(const vtkPointInterpolator&) = delete; 321 322 }; 323 324 #endif 325