1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkVoxelGrid.h
5 
6   Copyright (c) Kitware, Inc.
7   All rights reserved.
8   See LICENSE file 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   vtkVoxelGrid
17  * @brief   subsample points using uniform binning
18  *
19  *
20  * vtkVoxelGrid is a filter that subsamples a point cloud based on a regular
21  * binning of space. Basically the algorithm operates by dividing space into
22  * a volume of M x N x O bins, and then for each bin averaging all of the
23  * points positions into a single representative point. Several strategies for
24  * computing the binning can be used: 1) manual configuration of a requiring
25  * specifying bin dimensions (the bounds are calculated from the data); 2) by
26  * explicit specification of the bin size in world coordinates (x-y-z
27  * lengths); and 3) an automatic process in which the user specifies an
28  * approximate, average number of points per bin and dimensions and bin size
29  * are computed automatically. (Note that under the hood a
30  * vtkStaticPointLocator is used.)
31  *
32  * While any vtkPointSet type can be provided as input, the output is
33  * represented by an explicit representation of points via a
34  * vtkPolyData. This output polydata will populate its instance of vtkPoints,
35  * but no cells will be defined (i.e., no vtkVertex or vtkPolyVertex are
36  * contained in the output).
37  *
38  * @warning
39  * This class has been threaded with vtkSMPTools. Using TBB or other
40  * non-sequential type (set in the CMake variable
41  * VTK_SMP_IMPLEMENTATION_TYPE) may improve performance significantly.
42  *
43  * @sa
44  * vtkStaticPointLocator vtkPointCloudFilter vtkQuadricClustering
45 */
46 
47 #ifndef vtkVoxelGrid_h
48 #define vtkVoxelGrid_h
49 
50 #include "vtkFiltersPointsModule.h" // For export macro
51 #include "vtkPolyDataAlgorithm.h"
52 
53 class vtkStaticPointLocator;
54 class vtkInterpolationKernel;
55 
56 
57 class VTKFILTERSPOINTS_EXPORT vtkVoxelGrid : public vtkPolyDataAlgorithm
58 {
59 public:
60   //@{
61   /**
62    * Standard methods for instantiating, obtaining type information, and
63    * printing information.
64    */
65   static vtkVoxelGrid *New();
66   vtkTypeMacro(vtkVoxelGrid,vtkPolyDataAlgorithm);
67   void PrintSelf(ostream& os, vtkIndent indent) override;
68   //@}
69 
70   /**
71    * This enum is used to configure the operation of the filter.
72    */
73   enum Style
74   {
75     MANUAL=0,
76     SPECIFY_LEAF_SIZE=1,
77     AUTOMATIC=2
78   };
79 
80   //@{
81   /**
82    * Configure how the filter is to operate. The user can choose to manually
83    * specify the binning volume (by setting its dimensions via MANUAL style); or
84    * specify a leaf bin size in the x-y-z directions (SPECIFY_LEAF_SIZE); or
85    * in AUTOMATIC style, use a rough average number of points in each bin
86    * guide the bin size and binning volume dimensions. By default, AUTOMATIC
87    * configuration style is used.
88    */
89   vtkSetMacro(ConfigurationStyle,int);
90   vtkGetMacro(ConfigurationStyle,int);
SetConfigurationStyleToManual()91   void SetConfigurationStyleToManual()
92     { this->SetConfigurationStyle(MANUAL); }
SetConfigurationStyleToLeafSize()93   void SetConfigurationStyleToLeafSize()
94     { this->SetConfigurationStyle(SPECIFY_LEAF_SIZE); }
SetConfigurationStyleToAutomatic()95   void SetConfigurationStyleToAutomatic()
96     { this->SetConfigurationStyle(AUTOMATIC); }
97   //@}
98 
99   //@{
100   /**
101    * Set the number of divisions in x-y-z directions (the binning volume
102    * dimensions). This data member is used when the configuration style is
103    * set to MANUAL. Note that these values may be adjusted if <1 or too
104    * large.
105    */
106   vtkSetVector3Macro(Divisions,int);
107   vtkGetVectorMacro(Divisions,int,3);
108   //@}
109 
110   //@{
111   /**
112    * Set the bin size in the x-y-z directions. This data member is
113    * used when the configuration style is set to SPECIFY_LEAF_SIZE. The class will
114    * use these x-y-z lengths, within the bounding box of the point cloud,
115    * to determine the binning dimensions.
116    */
117   vtkSetVector3Macro(LeafSize,double);
118   vtkGetVectorMacro(LeafSize,double,3);
119   //@}
120 
121   //@{
122   /**
123    * Specify the average number of points in each bin. Larger values
124    * result in higher rates of subsampling. This data member is used when the
125    * configuration style is set to AUTOMATIC. The class will automatically
126    * determine the binning dimensions in the x-y-z directions.
127    */
128   vtkSetClampMacro(NumberOfPointsPerBin,int,1,VTK_INT_MAX);
129   vtkGetMacro(NumberOfPointsPerBin,int);
130   //@}
131 
132   //@{
133   /**
134    * Specify an interpolation kernel to combine the point attributes. By
135    * default a vtkLinearKernel is used (i.e., average values). The
136    * interpolation kernel changes the basis of the interpolation.
137    */
138   void SetKernel(vtkInterpolationKernel *kernel);
139   vtkGetObjectMacro(Kernel,vtkInterpolationKernel);
140   //@}
141 
142 protected:
143   vtkVoxelGrid();
144   ~vtkVoxelGrid() override;
145 
146   vtkStaticPointLocator *Locator;
147   int ConfigurationStyle;
148 
149   int Divisions[3];
150   double LeafSize[3];
151   int NumberOfPointsPerBin;
152   vtkInterpolationKernel *Kernel;
153 
154   int RequestData(vtkInformation *, vtkInformationVector **,
155                           vtkInformationVector *) override;
156   int FillInputPortInformation(int port, vtkInformation *info) override;
157 
158 private:
159   vtkVoxelGrid(const vtkVoxelGrid&) = delete;
160   void operator=(const vtkVoxelGrid&) = delete;
161 
162 };
163 
164 #endif
165