1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkDicer.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   vtkDicer
17  * @brief   abstract superclass to divide dataset into pieces
18  *
19  * Subclasses of vtkDicer divides the input dataset into separate
20  * pieces.  These pieces can then be operated on by other filters
21  * (e.g., vtkThreshold). One application is to break very large
22  * polygonal models into pieces and performing viewing and occlusion
23  * culling on the pieces. Multiple pieces can also be streamed through
24  * the visualization pipeline.
25  *
26  * To use this filter, you must specify the execution mode of the
27  * filter; i.e., set the way that the piece size is controlled (do
28  * this by setting the DiceMode ivar). The filter does not change the
29  * geometry or topology of the input dataset, rather it generates
30  * integer numbers that indicate which piece a particular point
31  * belongs to (i.e., it modifies the point and cell attribute
32  * data). The integer number can be placed into the output scalar
33  * data, or the output field data.
34  *
35  * @warning
36  * The number of pieces generated may not equal the specified number
37  * of pieces. Use the method GetNumberOfActualPieces() after filter
38  * execution to get the actual number of pieces generated.
39  *
40  * @sa
41  * vtkOBBDicer vtkConnectedDicer vtkSpatialDicer
42  */
43 
44 #ifndef vtkDicer_h
45 #define vtkDicer_h
46 
47 #include "vtkDataSetAlgorithm.h"
48 #include "vtkFiltersGeneralModule.h" // For export macro
49 
50 #define VTK_DICE_MODE_NUMBER_OF_POINTS 0
51 #define VTK_DICE_MODE_SPECIFIED_NUMBER 1
52 #define VTK_DICE_MODE_MEMORY_LIMIT 2
53 
54 class VTKFILTERSGENERAL_EXPORT vtkDicer : public vtkDataSetAlgorithm
55 {
56 public:
57   vtkTypeMacro(vtkDicer, vtkDataSetAlgorithm);
58   void PrintSelf(ostream& os, vtkIndent indent) override;
59 
60   ///@{
61   /**
62    * Set/Get the flag which controls whether to generate point scalar
63    * data or point field data. If this flag is off, scalar data is
64    * generated.  Otherwise, field data is generated. Note that the
65    * generated the data are integer numbers indicating which piece a
66    * particular point belongs to.
67    */
68   vtkSetMacro(FieldData, vtkTypeBool);
69   vtkGetMacro(FieldData, vtkTypeBool);
70   vtkBooleanMacro(FieldData, vtkTypeBool);
71   ///@}
72 
73   ///@{
74   /**
75    * Specify the method to determine how many pieces the data should be
76    * broken into. By default, the number of points per piece is used.
77    */
78   vtkSetClampMacro(DiceMode, int, VTK_DICE_MODE_NUMBER_OF_POINTS, VTK_DICE_MODE_MEMORY_LIMIT);
79   vtkGetMacro(DiceMode, int);
SetDiceModeToNumberOfPointsPerPiece()80   void SetDiceModeToNumberOfPointsPerPiece() { this->SetDiceMode(VTK_DICE_MODE_NUMBER_OF_POINTS); }
SetDiceModeToSpecifiedNumberOfPieces()81   void SetDiceModeToSpecifiedNumberOfPieces() { this->SetDiceMode(VTK_DICE_MODE_SPECIFIED_NUMBER); }
SetDiceModeToMemoryLimitPerPiece()82   void SetDiceModeToMemoryLimitPerPiece() { this->SetDiceMode(VTK_DICE_MODE_MEMORY_LIMIT); }
83   ///@}
84 
85   ///@{
86   /**
87    * Use the following method after the filter has updated to
88    * determine the actual number of pieces the data was separated
89    * into.
90    */
91   vtkGetMacro(NumberOfActualPieces, int);
92   ///@}
93 
94   ///@{
95   /**
96    * Control piece size based on the maximum number of points per piece.
97    * (This ivar has effect only when the DiceMode is set to
98    * SetDiceModeToNumberOfPoints().)
99    */
100   vtkSetClampMacro(NumberOfPointsPerPiece, int, 1000, VTK_INT_MAX);
101   vtkGetMacro(NumberOfPointsPerPiece, int);
102   ///@}
103 
104   ///@{
105   /**
106    * Set/Get the number of pieces the object is to be separated into.
107    * (This ivar has effect only when the DiceMode is set to
108    * SetDiceModeToSpecifiedNumber()). Note that the ivar
109    * NumberOfPieces is a target - depending on the particulars of the
110    * data, more or less number of pieces than the target value may be
111    * created.
112    */
113   vtkSetClampMacro(NumberOfPieces, int, 1, VTK_INT_MAX);
114   vtkGetMacro(NumberOfPieces, int);
115   ///@}
116 
117   ///@{
118   /**
119    * Control piece size based on a memory limit.  (This ivar has
120    * effect only when the DiceMode is set to
121    * SetDiceModeToMemoryLimit()). The memory limit should be set in
122    * kibibytes (1024 bytes).
123    */
124   vtkSetClampMacro(MemoryLimit, unsigned long, 100, VTK_INT_MAX);
125   vtkGetMacro(MemoryLimit, unsigned long);
126   ///@}
127 
128 protected:
129   vtkDicer();
130   ~vtkDicer() override = default;
131 
132   virtual void UpdatePieceMeasures(vtkDataSet* input);
133 
134   int NumberOfPointsPerPiece;
135   int NumberOfPieces;
136   unsigned long MemoryLimit;
137   int NumberOfActualPieces;
138   vtkTypeBool FieldData;
139   int DiceMode;
140 
141 private:
142   vtkDicer(const vtkDicer&) = delete;
143   void operator=(const vtkDicer&) = delete;
144 };
145 
146 #endif
147