1 /*=========================================================================
2
3 Program: Visualization Toolkit
4 Module: vtkGenericGlyph3DFilter.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 vtkGenericGlyph3DFilter
17 * @brief copy oriented and scaled glyph geometry to every input point
18 *
19 * vtkGenericGlyph3DFilter is a filter that copies a geometric representation (called
20 * a glyph) to every point in the input dataset. The glyph is defined with
21 * polygonal data from a source filter input. The glyph may be oriented
22 * along the input vectors or normals, and it may be scaled according to
23 * scalar data or vector magnitude. More than one glyph may be used by
24 * creating a table of source objects, each defining a different glyph. If a
25 * table of glyphs is defined, then the table can be indexed into by using
26 * either scalar value or vector magnitude.
27 *
28 * To use this object you'll have to provide an input dataset and a source
29 * to define the glyph. Then decide whether you want to scale the glyph and
30 * how to scale the glyph (using scalar value or vector magnitude). Next
31 * decide whether you want to orient the glyph, and whether to use the
32 * vector data or normal data to orient it. Finally, decide whether to use a
33 * table of glyphs, or just a single glyph. If you use a table of glyphs,
34 * you'll have to decide whether to index into it with scalar value or with
35 * vector magnitude.
36 *
37 * @warning
38 * Contrary to vtkGlyph3D, the only way to specify which attributes will be
39 * used for scaling, coloring and orienting is through SelectInputScalars(),
40 * SelectInputVectors() and SelectInputNormals().
41 *
42 * @warning
43 * The scaling of the glyphs is controlled by the ScaleFactor ivar multiplied
44 * by the scalar value at each point (if VTK_SCALE_BY_SCALAR is set), or
45 * multiplied by the vector magnitude (if VTK_SCALE_BY_VECTOR is set),
46 * Alternatively (if VTK_SCALE_BY_VECTORCOMPONENTS is set), the scaling
47 * may be specified for x,y,z using the vector components. The
48 * scale factor can be further controlled by enabling clamping using the
49 * Clamping ivar. If clamping is enabled, the scale is normalized by the
50 * Range ivar, and then multiplied by the scale factor. The normalization
51 * process includes clamping the scale value between (0,1).
52 *
53 * @warning
54 * Typically this object operates on input data with scalar and/or vector
55 * data. However, scalar and/or vector aren't necessary, and it can be used
56 * to copy data from a single source to each point. In this case the scale
57 * factor can be used to uniformly scale the glyphs.
58 *
59 * @warning
60 * The object uses "vector" data to scale glyphs, orient glyphs, and/or index
61 * into a table of glyphs. You can choose to use either the vector or normal
62 * data at each input point. Use the method SetVectorModeToUseVector() to use
63 * the vector input data, and SetVectorModeToUseNormal() to use the
64 * normal input data.
65 *
66 * @warning
67 * If you do use a table of glyphs, make sure to set the Range ivar to make
68 * sure the index into the glyph table is computed correctly.
69 *
70 * @warning
71 * You can turn off scaling of the glyphs completely by using the Scaling
72 * ivar. You can also turn off scaling due to data (either vector or scalar)
73 * by using the SetScaleModeToDataScalingOff() method.
74 *
75 * @sa
76 * vtkTensorGlyph
77 */
78
79 #ifndef vtkGenericGlyph3DFilter_h
80 #define vtkGenericGlyph3DFilter_h
81
82 #include "vtkFiltersGenericModule.h" // For export macro
83 #include "vtkPolyDataAlgorithm.h"
84
85 #define VTK_SCALE_BY_SCALAR 0
86 #define VTK_SCALE_BY_VECTOR 1
87 #define VTK_SCALE_BY_VECTORCOMPONENTS 2
88 #define VTK_DATA_SCALING_OFF 3
89
90 #define VTK_COLOR_BY_SCALE 0
91 #define VTK_COLOR_BY_SCALAR 1
92 #define VTK_COLOR_BY_VECTOR 2
93
94 #define VTK_USE_VECTOR 0
95 #define VTK_USE_NORMAL 1
96 #define VTK_VECTOR_ROTATION_OFF 2
97
98 #define VTK_INDEXING_OFF 0
99 #define VTK_INDEXING_BY_SCALAR 1
100 #define VTK_INDEXING_BY_VECTOR 2
101
102 class VTKFILTERSGENERIC_EXPORT vtkGenericGlyph3DFilter : public vtkPolyDataAlgorithm
103 {
104 public:
105 vtkTypeMacro(vtkGenericGlyph3DFilter,vtkPolyDataAlgorithm);
106 void PrintSelf(ostream& os, vtkIndent indent) override;
107
108 /**
109 * Construct object with scaling on, scaling mode is by scalar value,
110 * scale factor = 1.0, the range is (0,1), orient geometry is on, and
111 * orientation is by vector. Clamping and indexing are turned off. No
112 * initial sources are defined.
113 */
114 static vtkGenericGlyph3DFilter *New();
115
116 /**
117 * Set the source to use for the glyph.
118 */
SetSourceData(vtkPolyData * pd)119 void SetSourceData(vtkPolyData *pd) {this->SetSourceData(0,pd);};
120
121 /**
122 * Specify a source object at a specified table location.
123 */
124 void SetSourceData(int id, vtkPolyData *pd);
125
126 /**
127 * Get a pointer to a source object at a specified table location.
128 */
129 vtkPolyData *GetSource(int id=0);
130
131 //@{
132 /**
133 * Turn on/off scaling of source geometry.
134 */
135 vtkSetMacro(Scaling,vtkTypeBool);
136 vtkBooleanMacro(Scaling,vtkTypeBool);
137 vtkGetMacro(Scaling,vtkTypeBool);
138 //@}
139
140 //@{
141 /**
142 * Either scale by scalar or by vector/normal magnitude.
143 */
144 vtkSetMacro(ScaleMode,int);
145 vtkGetMacro(ScaleMode,int);
SetScaleModeToScaleByScalar()146 void SetScaleModeToScaleByScalar()
147 {this->SetScaleMode(VTK_SCALE_BY_SCALAR);};
SetScaleModeToScaleByVector()148 void SetScaleModeToScaleByVector()
149 {this->SetScaleMode(VTK_SCALE_BY_VECTOR);};
SetScaleModeToScaleByVectorComponents()150 void SetScaleModeToScaleByVectorComponents()
151 {this->SetScaleMode(VTK_SCALE_BY_VECTORCOMPONENTS);};
SetScaleModeToDataScalingOff()152 void SetScaleModeToDataScalingOff()
153 {this->SetScaleMode(VTK_DATA_SCALING_OFF);};
154 const char *GetScaleModeAsString();
155 //@}
156
157 //@{
158 /**
159 * Either color by scale, scalar or by vector/normal magnitude.
160 */
161 vtkSetMacro(ColorMode,int);
162 vtkGetMacro(ColorMode,int);
SetColorModeToColorByScale()163 void SetColorModeToColorByScale()
164 {this->SetColorMode(VTK_COLOR_BY_SCALE);};
SetColorModeToColorByScalar()165 void SetColorModeToColorByScalar()
166 {this->SetColorMode(VTK_COLOR_BY_SCALAR);};
SetColorModeToColorByVector()167 void SetColorModeToColorByVector()
168 {this->SetColorMode(VTK_COLOR_BY_VECTOR);};
169 const char *GetColorModeAsString();
170 //@}
171
172 //@{
173 /**
174 * Specify scale factor to scale object by.
175 */
176 vtkSetMacro(ScaleFactor,double);
177 vtkGetMacro(ScaleFactor,double);
178 //@}
179
180 //@{
181 /**
182 * Specify range to map scalar values into.
183 */
184 vtkSetVector2Macro(Range,double);
185 vtkGetVectorMacro(Range,double,2);
186 //@}
187
188 //@{
189 /**
190 * Turn on/off orienting of input geometry along vector/normal.
191 */
192 vtkSetMacro(Orient,vtkTypeBool);
193 vtkBooleanMacro(Orient,vtkTypeBool);
194 vtkGetMacro(Orient,vtkTypeBool);
195 //@}
196
197 //@{
198 /**
199 * Turn on/off clamping of "scalar" values to range. (Scalar value may be
200 * vector magnitude if ScaleByVector() is enabled.)
201 */
202 vtkSetMacro(Clamping,vtkTypeBool);
203 vtkBooleanMacro(Clamping,vtkTypeBool);
204 vtkGetMacro(Clamping,vtkTypeBool);
205 //@}
206
207 //@{
208 /**
209 * Specify whether to use vector or normal to perform vector operations.
210 */
211 vtkSetMacro(VectorMode,int);
212 vtkGetMacro(VectorMode,int);
SetVectorModeToUseVector()213 void SetVectorModeToUseVector() {this->SetVectorMode(VTK_USE_VECTOR);};
SetVectorModeToUseNormal()214 void SetVectorModeToUseNormal() {this->SetVectorMode(VTK_USE_NORMAL);};
SetVectorModeToVectorRotationOff()215 void SetVectorModeToVectorRotationOff()
216 {this->SetVectorMode(VTK_VECTOR_ROTATION_OFF);};
217 const char *GetVectorModeAsString();
218 //@}
219
220 //@{
221 /**
222 * Index into table of sources by scalar, by vector/normal magnitude, or
223 * no indexing. If indexing is turned off, then the first source glyph in
224 * the table of glyphs is used.
225 */
226 vtkSetMacro(IndexMode,int);
227 vtkGetMacro(IndexMode,int);
SetIndexModeToScalar()228 void SetIndexModeToScalar() {this->SetIndexMode(VTK_INDEXING_BY_SCALAR);};
SetIndexModeToVector()229 void SetIndexModeToVector() {this->SetIndexMode(VTK_INDEXING_BY_VECTOR);};
SetIndexModeToOff()230 void SetIndexModeToOff() {this->SetIndexMode(VTK_INDEXING_OFF);};
231 const char *GetIndexModeAsString();
232 //@}
233
234 //@{
235 /**
236 * Enable/disable the generation of point ids as part of the output. The
237 * point ids are the id of the input generating point. The point ids are
238 * stored in the output point field data and named "InputPointIds". Point
239 * generation is useful for debugging and pick operations.
240 */
241 vtkSetMacro(GeneratePointIds,vtkTypeBool);
242 vtkGetMacro(GeneratePointIds,vtkTypeBool);
243 vtkBooleanMacro(GeneratePointIds,vtkTypeBool);
244 //@}
245
246 //@{
247 /**
248 * Set/Get the name of the PointIds array if generated. By default the Ids
249 * are named "InputPointIds", but this can be changed with this function.
250 */
251 vtkSetStringMacro(PointIdsName);
252 vtkGetStringMacro(PointIdsName);
253 //@}
254
255 //@{
256 /**
257 * If you want to use an arbitrary scalars array, then set its name here.
258 * By default this in nullptr and the filter will use the active scalar array.
259 */
260 vtkGetStringMacro(InputScalarsSelection);
SelectInputScalars(const char * fieldName)261 void SelectInputScalars(const char *fieldName)
262 {this->SetInputScalarsSelection(fieldName);}
263 //@}
264
265 //@{
266 /**
267 * If you want to use an arbitrary vectors array, then set its name here.
268 * By default this in nullptr and the filter will use the active vector array.
269 */
270 vtkGetStringMacro(InputVectorsSelection);
SelectInputVectors(const char * fieldName)271 void SelectInputVectors(const char *fieldName)
272 {this->SetInputVectorsSelection(fieldName);}
273 //@}
274
275 //@{
276 /**
277 * If you want to use an arbitrary normals array, then set its name here.
278 * By default this in nullptr and the filter will use the active normal array.
279 */
280 vtkGetStringMacro(InputNormalsSelection);
SelectInputNormals(const char * fieldName)281 void SelectInputNormals(const char *fieldName)
282 {this->SetInputNormalsSelection(fieldName);}
283 //@}
284
285 protected:
286 vtkGenericGlyph3DFilter();
287 ~vtkGenericGlyph3DFilter() override;
288
289 int FillInputPortInformation(int, vtkInformation*) override;
290
291 int RequestData(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override;
292 int RequestInformation(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override;
293 int RequestUpdateExtent(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override;
294 vtkPolyData **Source; // Geometry to copy to each point
295 vtkTypeBool Scaling; // Determine whether scaling of geometry is performed
296 int ScaleMode; // Scale by scalar value or vector magnitude
297 int ColorMode; // new scalars based on scale, scalar or vector
298 double ScaleFactor; // Scale factor to use to scale geometry
299 double Range[2]; // Range to use to perform scalar scaling
300 vtkTypeBool Orient; // boolean controls whether to "orient" data
301 int VectorMode; // Orient/scale via normal or via vector data
302 vtkTypeBool Clamping; // whether to clamp scale factor
303 int IndexMode; // what to use to index into glyph table
304 vtkTypeBool GeneratePointIds; // produce input points ids for each output point
305 char *PointIdsName;
306
307 char *InputScalarsSelection;
308 char *InputVectorsSelection;
309 char *InputNormalsSelection;
310 vtkSetStringMacro(InputScalarsSelection);
311 vtkSetStringMacro(InputVectorsSelection);
312 vtkSetStringMacro(InputNormalsSelection);
313
314 private:
315 vtkGenericGlyph3DFilter(const vtkGenericGlyph3DFilter&) = delete;
316 void operator=(const vtkGenericGlyph3DFilter&) = delete;
317 };
318
319 //@{
320 /**
321 * Return the method of scaling as a descriptive character string.
322 */
GetScaleModeAsString()323 inline const char *vtkGenericGlyph3DFilter::GetScaleModeAsString()
324 {
325 if ( this->ScaleMode == VTK_SCALE_BY_SCALAR )
326 {
327 return "ScaleByScalar";
328 }
329 else if ( this->ScaleMode == VTK_SCALE_BY_VECTOR )
330 {
331 return "ScaleByVector";
332 }
333 else
334 {
335 return "DataScalingOff";
336 }
337 }
338 //@}
339
340 //@{
341 /**
342 * Return the method of coloring as a descriptive character string.
343 */
GetColorModeAsString()344 inline const char *vtkGenericGlyph3DFilter::GetColorModeAsString()
345 {
346 if ( this->ColorMode == VTK_COLOR_BY_SCALAR )
347 {
348 return "ColorByScalar";
349 }
350 else if ( this->ColorMode == VTK_COLOR_BY_VECTOR )
351 {
352 return "ColorByVector";
353 }
354 else
355 {
356 return "ColorByScale";
357 }
358 }
359 //@}
360
361 //@{
362 /**
363 * Return the vector mode as a character string.
364 */
GetVectorModeAsString()365 inline const char *vtkGenericGlyph3DFilter::GetVectorModeAsString()
366 {
367 if ( this->VectorMode == VTK_USE_VECTOR)
368 {
369 return "UseVector";
370 }
371 else if ( this->VectorMode == VTK_USE_NORMAL)
372 {
373 return "UseNormal";
374 }
375 else
376 {
377 return "VectorRotationOff";
378 }
379 }
380 //@}
381
382 //@{
383 /**
384 * Return the index mode as a character string.
385 */
GetIndexModeAsString()386 inline const char *vtkGenericGlyph3DFilter::GetIndexModeAsString()
387 {
388 if ( this->IndexMode == VTK_INDEXING_OFF)
389 {
390 return "IndexingOff";
391 }
392 else if ( this->IndexMode == VTK_INDEXING_BY_SCALAR)
393 {
394 return "IndexingByScalar";
395 }
396 else
397 {
398 return "IndexingByVector";
399 }
400 }
401 //@}
402
403 #endif
404