1 /*=========================================================================
2
3 Program: Visualization Toolkit
4 Module: vtkGlyph3D.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 vtkGlyph3D
17 * @brief copy oriented and scaled glyph geometry to every input point
18 *
19 * vtkGlyph3D 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 * The scaling of the glyphs is controlled by the ScaleFactor ivar multiplied
39 * by the scalar value at each point (if VTK_SCALE_BY_SCALAR is set), or
40 * multiplied by the vector magnitude (if VTK_SCALE_BY_VECTOR is set),
41 * Alternatively (if VTK_SCALE_BY_VECTORCOMPONENTS is set), the scaling
42 * may be specified for x,y,z using the vector components. The
43 * scale factor can be further controlled by enabling clamping using the
44 * Clamping ivar. If clamping is enabled, the scale is normalized by the
45 * Range ivar, and then multiplied by the scale factor. The normalization
46 * process includes clamping the scale value between (0,1).
47 *
48 * @warning
49 * Typically this object operates on input data with scalar and/or vector
50 * data. However, scalar and/or vector aren't necessary, and it can be used
51 * to copy data from a single source to each point. In this case the scale
52 * factor can be used to uniformly scale the glyphs.
53 *
54 * @warning
55 * The object uses "vector" data to scale glyphs, orient glyphs, and/or index
56 * into a table of glyphs. You can choose to use either the vector or normal
57 * data at each input point. Use the method SetVectorModeToUseVector() to use
58 * the vector input data, and SetVectorModeToUseNormal() to use the
59 * normal input data.
60 *
61 * @warning
62 * If you do use a table of glyphs, make sure to set the Range ivar to make
63 * sure the index into the glyph table is computed correctly.
64 *
65 * @warning
66 * You can turn off scaling of the glyphs completely by using the Scaling
67 * ivar. You can also turn off scaling due to data (either vector or scalar)
68 * by using the SetScaleModeToDataScalingOff() method.
69 *
70 * @warning
71 * You can set what arrays to use for the scalars, vectors, normals, and
72 * color scalars by using the SetInputArrayToProcess methods in
73 * vtkAlgorithm. The first array is scalars, the next vectors, the next
74 * normals and finally color scalars.
75 *
76 * @sa
77 * vtkTensorGlyph
78 */
79
80 #ifndef vtkGlyph3D_h
81 #define vtkGlyph3D_h
82
83 #include "vtkFiltersCoreModule.h" // For export macro
84 #include "vtkPolyDataAlgorithm.h"
85
86 #define VTK_SCALE_BY_SCALAR 0
87 #define VTK_SCALE_BY_VECTOR 1
88 #define VTK_SCALE_BY_VECTORCOMPONENTS 2
89 #define VTK_DATA_SCALING_OFF 3
90
91 #define VTK_COLOR_BY_SCALE 0
92 #define VTK_COLOR_BY_SCALAR 1
93 #define VTK_COLOR_BY_VECTOR 2
94
95 #define VTK_USE_VECTOR 0
96 #define VTK_USE_NORMAL 1
97 #define VTK_VECTOR_ROTATION_OFF 2
98
99 #define VTK_INDEXING_OFF 0
100 #define VTK_INDEXING_BY_SCALAR 1
101 #define VTK_INDEXING_BY_VECTOR 2
102
103 class vtkTransform;
104
105 class VTKFILTERSCORE_EXPORT vtkGlyph3D : public vtkPolyDataAlgorithm
106 {
107 public:
108 vtkTypeMacro(vtkGlyph3D,vtkPolyDataAlgorithm);
109 void PrintSelf(ostream& os, vtkIndent indent) override;
110
111 /**
112 * Construct object with scaling on, scaling mode is by scalar value,
113 * scale factor = 1.0, the range is (0,1), orient geometry is on, and
114 * orientation is by vector. Clamping and indexing are turned off. No
115 * initial sources are defined.
116 */
117 static vtkGlyph3D *New();
118
119 /**
120 * Set the source to use for the glyph.
121 * Note that this method does not connect the pipeline. The algorithm will
122 * work on the input data as it is without updating the producer of the data.
123 * See SetSourceConnection for connecting the pipeline.
124 */
SetSourceData(vtkPolyData * pd)125 void SetSourceData(vtkPolyData *pd) {this->SetSourceData(0,pd);};
126
127 /**
128 * Specify a source object at a specified table location.
129 * Note that this method does not connect the pipeline. The algorithm will
130 * work on the input data as it is without updating the producer of the data.
131 * See SetSourceConnection for connecting the pipeline.
132 */
133 void SetSourceData(int id, vtkPolyData *pd);
134
135 //@{
136 /**
137 * Specify a source object at a specified table location. New style.
138 * Source connection is stored in port 1. This method is equivalent
139 * to SetInputConnection(1, id, outputPort).
140 */
141 void SetSourceConnection(int id, vtkAlgorithmOutput* algOutput);
SetSourceConnection(vtkAlgorithmOutput * algOutput)142 void SetSourceConnection(vtkAlgorithmOutput* algOutput)
143 {
144 this->SetSourceConnection(0, algOutput);
145 }
146 //@}
147
148 /**
149 * Get a pointer to a source object at a specified table location.
150 */
151 vtkPolyData *GetSource(int id=0);
152
153 //@{
154 /**
155 * Turn on/off scaling of source geometry.
156 */
157 vtkSetMacro(Scaling,vtkTypeBool);
158 vtkBooleanMacro(Scaling,vtkTypeBool);
159 vtkGetMacro(Scaling,vtkTypeBool);
160 //@}
161
162 //@{
163 /**
164 * Either scale by scalar or by vector/normal magnitude.
165 */
166 vtkSetMacro(ScaleMode,int);
167 vtkGetMacro(ScaleMode,int);
SetScaleModeToScaleByScalar()168 void SetScaleModeToScaleByScalar()
169 {this->SetScaleMode(VTK_SCALE_BY_SCALAR);};
SetScaleModeToScaleByVector()170 void SetScaleModeToScaleByVector()
171 {this->SetScaleMode(VTK_SCALE_BY_VECTOR);};
SetScaleModeToScaleByVectorComponents()172 void SetScaleModeToScaleByVectorComponents()
173 {this->SetScaleMode(VTK_SCALE_BY_VECTORCOMPONENTS);};
SetScaleModeToDataScalingOff()174 void SetScaleModeToDataScalingOff()
175 {this->SetScaleMode(VTK_DATA_SCALING_OFF);};
176 const char *GetScaleModeAsString();
177 //@}
178
179 //@{
180 /**
181 * Either color by scale, scalar or by vector/normal magnitude.
182 */
183 vtkSetMacro(ColorMode,int);
184 vtkGetMacro(ColorMode,int);
SetColorModeToColorByScale()185 void SetColorModeToColorByScale()
186 {this->SetColorMode(VTK_COLOR_BY_SCALE);};
SetColorModeToColorByScalar()187 void SetColorModeToColorByScalar()
188 {this->SetColorMode(VTK_COLOR_BY_SCALAR);};
SetColorModeToColorByVector()189 void SetColorModeToColorByVector()
190 {this->SetColorMode(VTK_COLOR_BY_VECTOR);};
191 const char *GetColorModeAsString();
192 //@}
193
194 //@{
195 /**
196 * Specify scale factor to scale object by.
197 */
198 vtkSetMacro(ScaleFactor,double);
199 vtkGetMacro(ScaleFactor,double);
200 //@}
201
202 //@{
203 /**
204 * Specify range to map scalar values into.
205 */
206 vtkSetVector2Macro(Range,double);
207 vtkGetVectorMacro(Range,double,2);
208 //@}
209
210 //@{
211 /**
212 * Turn on/off orienting of input geometry along vector/normal.
213 */
214 vtkSetMacro(Orient,vtkTypeBool);
215 vtkBooleanMacro(Orient,vtkTypeBool);
216 vtkGetMacro(Orient,vtkTypeBool);
217 //@}
218
219 //@{
220 /**
221 * Turn on/off clamping of "scalar" values to range. (Scalar value may be
222 * vector magnitude if ScaleByVector() is enabled.)
223 */
224 vtkSetMacro(Clamping,vtkTypeBool);
225 vtkBooleanMacro(Clamping,vtkTypeBool);
226 vtkGetMacro(Clamping,vtkTypeBool);
227 //@}
228
229 //@{
230 /**
231 * Specify whether to use vector or normal to perform vector operations.
232 */
233 vtkSetMacro(VectorMode,int);
234 vtkGetMacro(VectorMode,int);
SetVectorModeToUseVector()235 void SetVectorModeToUseVector() {this->SetVectorMode(VTK_USE_VECTOR);};
SetVectorModeToUseNormal()236 void SetVectorModeToUseNormal() {this->SetVectorMode(VTK_USE_NORMAL);};
SetVectorModeToVectorRotationOff()237 void SetVectorModeToVectorRotationOff()
238 {this->SetVectorMode(VTK_VECTOR_ROTATION_OFF);};
239 const char *GetVectorModeAsString();
240 //@}
241
242 //@{
243 /**
244 * Index into table of sources by scalar, by vector/normal magnitude, or
245 * no indexing. If indexing is turned off, then the first source glyph in
246 * the table of glyphs is used. Note that indexing mode will only use the
247 * InputScalarsSelection array and not the InputColorScalarsSelection
248 * as the scalar source if an array is specified.
249 */
250 vtkSetMacro(IndexMode,int);
251 vtkGetMacro(IndexMode,int);
SetIndexModeToScalar()252 void SetIndexModeToScalar() {this->SetIndexMode(VTK_INDEXING_BY_SCALAR);};
SetIndexModeToVector()253 void SetIndexModeToVector() {this->SetIndexMode(VTK_INDEXING_BY_VECTOR);};
SetIndexModeToOff()254 void SetIndexModeToOff() {this->SetIndexMode(VTK_INDEXING_OFF);};
255 const char *GetIndexModeAsString();
256 //@}
257
258 //@{
259 /**
260 * Enable/disable the generation of point ids as part of the output. The
261 * point ids are the id of the input generating point. The point ids are
262 * stored in the output point field data and named "InputPointIds". Point
263 * generation is useful for debugging and pick operations.
264 */
265 vtkSetMacro(GeneratePointIds,vtkTypeBool);
266 vtkGetMacro(GeneratePointIds,vtkTypeBool);
267 vtkBooleanMacro(GeneratePointIds,vtkTypeBool);
268 //@}
269
270 //@{
271 /**
272 * Set/Get the name of the PointIds array if generated. By default the Ids
273 * are named "InputPointIds", but this can be changed with this function.
274 */
275 vtkSetStringMacro(PointIdsName);
276 vtkGetStringMacro(PointIdsName);
277 //@}
278
279 //@{
280 /**
281 * Enable/disable the generation of cell data as part of the output.
282 * The cell data at each cell will match the point data of the input
283 * at the glyphed point.
284 */
285 vtkSetMacro(FillCellData,vtkTypeBool);
286 vtkGetMacro(FillCellData,vtkTypeBool);
287 vtkBooleanMacro(FillCellData,vtkTypeBool);
288 //@}
289
290 /**
291 * This can be overwritten by subclass to return 0 when a point is
292 * blanked. Default implementation is to always return 1;
293 */
IsPointVisible(vtkDataSet *,vtkIdType)294 virtual int IsPointVisible(vtkDataSet*, vtkIdType) {return 1;};
295
296 //@{
297 /**
298 * When set, this is use to transform the source polydata before using it to
299 * generate the glyph. This is useful if one wanted to reorient the source,
300 * for example.
301 */
302 void SetSourceTransform(vtkTransform*);
303 vtkGetObjectMacro(SourceTransform, vtkTransform);
304 //@}
305
306 /**
307 * Overridden to include SourceTransform's MTime.
308 */
309 vtkMTimeType GetMTime() override;
310
311 //@{
312 /**
313 * Set/get the desired precision for the output types. See the documentation
314 * for the vtkAlgorithm::DesiredOutputPrecision enum for an explanation of
315 * the available precision settings.
316 */
317 vtkSetMacro(OutputPointsPrecision,int);
318 vtkGetMacro(OutputPointsPrecision,int);
319 //@}
320
321 protected:
322 vtkGlyph3D();
323 ~vtkGlyph3D() override;
324
325 int RequestData(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override;
326 int RequestUpdateExtent(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override;
327 int FillInputPortInformation(int, vtkInformation *) override;
328
329 vtkPolyData* GetSource(int idx, vtkInformationVector *sourceInfo);
330
331 //@{
332 /**
333 * Method called in RequestData() to do the actual data processing. This will
334 * glyph the \c input, filling up the \c output based on the filter
335 * parameters.
336 */
337 virtual bool Execute(vtkDataSet* input,
338 vtkInformationVector* sourceVector,
339 vtkPolyData* output);
340 virtual bool Execute(vtkDataSet* input,
341 vtkInformationVector* sourceVector,
342 vtkPolyData* output,
343 vtkDataArray *inSScalars,
344 vtkDataArray *inVectors);
345 //@}
346
347 vtkPolyData **Source; // Geometry to copy to each point
348 vtkTypeBool Scaling; // Determine whether scaling of geometry is performed
349 int ScaleMode; // Scale by scalar value or vector magnitude
350 int ColorMode; // new scalars based on scale, scalar or vector
351 double ScaleFactor; // Scale factor to use to scale geometry
352 double Range[2]; // Range to use to perform scalar scaling
353 int Orient; // boolean controls whether to "orient" data
354 int VectorMode; // Orient/scale via normal or via vector data
355 vtkTypeBool Clamping; // whether to clamp scale factor
356 int IndexMode; // what to use to index into glyph table
357 vtkTypeBool GeneratePointIds; // produce input points ids for each output point
358 vtkTypeBool FillCellData; // whether to fill output cell data
359 char *PointIdsName;
360 vtkTransform* SourceTransform;
361 int OutputPointsPrecision;
362
363 private:
364 vtkGlyph3D(const vtkGlyph3D&) = delete;
365 void operator=(const vtkGlyph3D&) = delete;
366 };
367
368 //@{
369 /**
370 * Return the method of scaling as a descriptive character string.
371 */
GetScaleModeAsString(void)372 inline const char *vtkGlyph3D::GetScaleModeAsString(void)
373 {
374 if ( this->ScaleMode == VTK_SCALE_BY_SCALAR )
375 {
376 return "ScaleByScalar";
377 }
378 else if ( this->ScaleMode == VTK_SCALE_BY_VECTOR )
379 {
380 return "ScaleByVector";
381 }
382 else
383 {
384 return "DataScalingOff";
385 }
386 }
387 //@}
388
389 //@{
390 /**
391 * Return the method of coloring as a descriptive character string.
392 */
GetColorModeAsString(void)393 inline const char *vtkGlyph3D::GetColorModeAsString(void)
394 {
395 if ( this->ColorMode == VTK_COLOR_BY_SCALAR )
396 {
397 return "ColorByScalar";
398 }
399 else if ( this->ColorMode == VTK_COLOR_BY_VECTOR )
400 {
401 return "ColorByVector";
402 }
403 else
404 {
405 return "ColorByScale";
406 }
407 }
408 //@}
409
410 //@{
411 /**
412 * Return the vector mode as a character string.
413 */
GetVectorModeAsString(void)414 inline const char *vtkGlyph3D::GetVectorModeAsString(void)
415 {
416 if ( this->VectorMode == VTK_USE_VECTOR)
417 {
418 return "UseVector";
419 }
420 else if ( this->VectorMode == VTK_USE_NORMAL)
421 {
422 return "UseNormal";
423 }
424 else
425 {
426 return "VectorRotationOff";
427 }
428 }
429 //@}
430
431 //@{
432 /**
433 * Return the index mode as a character string.
434 */
GetIndexModeAsString(void)435 inline const char *vtkGlyph3D::GetIndexModeAsString(void)
436 {
437 if ( this->IndexMode == VTK_INDEXING_OFF)
438 {
439 return "IndexingOff";
440 }
441 else if ( this->IndexMode == VTK_INDEXING_BY_SCALAR)
442 {
443 return "IndexingByScalar";
444 }
445 else
446 {
447 return "IndexingByVector";
448 }
449 }
450 //@}
451
452 #endif
453