1 /*=========================================================================
2 
3   Program:   Visualization Toolkit
4   Module:    vtkTensorGlyph.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   vtkTensorGlyph
17  * @brief   scale and orient glyph(s) according to eigenvalues and eigenvectors of symmetrical part
18  * of tensor
19  *
20  * vtkTensorGlyph is a filter that copies a geometric representation
21  * (specified as polygonal data) to every input point. The geometric
22  * representation, or glyph, can be scaled and/or rotated according to
23  * the tensor at the input point. Scaling and rotation is controlled
24  * by the eigenvalues/eigenvectors of the symmetrical part of the tensor
25  * as follows:
26  * For each tensor, the eigenvalues (and associated eigenvectors) are sorted
27  * to determine the major, medium, and minor eigenvalues/eigenvectors.
28  * The eigenvalue decomposition only makes sense for symmetric tensors,
29  * hence the need to only consider the symmetric part of the tensor, which is
30  * 1/2 (T + T.transposed()).
31  *
32  * If the boolean variable ThreeGlyphs is not set the major eigenvalue
33  * scales the glyph in the x-direction, the medium in the y-direction,
34  * and the minor in the z-direction. Then, the glyph is rotated so
35  * that the glyph's local x-axis lies along the major eigenvector,
36  * y-axis along the medium eigenvector, and z-axis along the minor.
37  *
38  * If the boolean variable ThreeGlyphs is set three glyphs are produced,
39  * each of them oriented along an eigenvector and scaled according to the
40  * corresponding eigenvector.
41  *
42  * If the boolean variable Symmetric is set each glyph is mirrored (2 or 6
43  * glyphs will be produced)
44  *
45  * The x-axis of the source glyph will correspond to the eigenvector
46  * on output. Point (0,0,0) in the source will be placed in the data point.
47  * Variable Length will normally correspond to the distance from the
48  * origin to the tip of the source glyph along the x-axis,
49  * but can be changed to produce other results when Symmetric is on,
50  * e.g. glyphs that do not touch or that overlap.
51  *
52  * Please note that when Symmetric is false it will generally be better
53  * to place the source glyph from (-0.5,0,0) to (0.5,0,0), i.e. centered
54  * at the origin. When symmetric is true the placement from (0,0,0) to
55  * (1,0,0) will generally be more convenient.
56  *
57  * A scale factor is provided to control the amount of scaling. Also, you
58  * can turn off scaling completely if desired. The boolean variable
59  * ClampScaling controls the maximum scaling (in conjunction with
60  * MaxScaleFactor.) This is useful in certain applications where
61  * singularities or large order of magnitude differences exist in
62  * the eigenvalues.
63  *
64  * If the boolean variable ColorGlyphs is set to true the glyphs are
65  * colored.  The glyphs can be colored using the input scalars
66  * (SetColorModeToScalars), which is the default, or colored using the
67  * eigenvalues (SetColorModeToEigenvalues).
68  *
69  * Another instance variable, ExtractEigenvalues, has been provided to
70  * control extraction of eigenvalues/eigenvectors. If this boolean is
71  * false, then eigenvalues/eigenvectors are not extracted, and the
72  * columns of the tensor are taken as the eigenvectors (the norm of
73  * column, always positive, is the eigenvalue).  This allows
74  * additional capability over the vtkGlyph3D object. That is, the
75  * glyph can be oriented in three directions instead of one.
76  *
77  * @par Thanks:
78  * Thanks to Jose Paulo Moitinho de Almeida for enhancements.
79  *
80  * @sa
81  * vtkGlyph3D vtkPointLoad vtkHyperStreamline
82  */
83 
84 #ifndef vtkTensorGlyph_h
85 #define vtkTensorGlyph_h
86 
87 #include "vtkFiltersCoreModule.h" // For export macro
88 #include "vtkPolyDataAlgorithm.h"
89 
90 class VTKFILTERSCORE_EXPORT vtkTensorGlyph : public vtkPolyDataAlgorithm
91 {
92 public:
93   ///@{
94   /**
95    * Standard methods for instantiation, obtaining type information, and
96    * printing.Construct object with scaling on and scale factor
97    * 1.0. Eigenvalues are extracted, glyphs are colored with input scalar
98    * data, and logarithmic scaling is turned off.
99    */
100   static vtkTensorGlyph* New();
101   vtkTypeMacro(vtkTensorGlyph, vtkPolyDataAlgorithm);
102   void PrintSelf(ostream& os, vtkIndent indent) override;
103   ///@}
104 
105   ///@{
106   /**
107    * Specify the geometry to copy to each point.
108    * Note that this method does not connect the pipeline. The algorithm will
109    * work on the input data as it is without updating the producer of the data.
110    * See SetSourceConnection for connecting the pipeline.
111    */
112   void SetSourceData(vtkPolyData* source);
113   vtkPolyData* GetSource();
114   ///@}
115 
116   ///@{
117   /**
118    * Specify a source object at a specified table location. New style.
119    * Source connection is stored in port 1. This method is equivalent
120    * to SetInputConnection(1, id, outputPort).
121    */
122   void SetSourceConnection(int id, vtkAlgorithmOutput* algOutput);
SetSourceConnection(vtkAlgorithmOutput * algOutput)123   void SetSourceConnection(vtkAlgorithmOutput* algOutput)
124   {
125     this->SetSourceConnection(0, algOutput);
126   }
127   ///@}
128 
129   ///@{
130   /**
131    * Turn on/off scaling of glyph with eigenvalues.
132    */
133   vtkSetMacro(Scaling, vtkTypeBool);
134   vtkGetMacro(Scaling, vtkTypeBool);
135   vtkBooleanMacro(Scaling, vtkTypeBool);
136   ///@}
137 
138   ///@{
139   /**
140    * Specify scale factor to scale object by. (Scale factor always affects
141    * output even if scaling is off.)
142    */
143   vtkSetMacro(ScaleFactor, double);
144   vtkGetMacro(ScaleFactor, double);
145   ///@}
146 
147   ///@{
148   /**
149    * Turn on/off drawing three glyphs
150    */
151   vtkSetMacro(ThreeGlyphs, vtkTypeBool);
152   vtkGetMacro(ThreeGlyphs, vtkTypeBool);
153   vtkBooleanMacro(ThreeGlyphs, vtkTypeBool);
154   ///@}
155 
156   ///@{
157   /**
158    * Turn on/off drawing a mirror of each glyph
159    */
160   vtkSetMacro(Symmetric, vtkTypeBool);
161   vtkGetMacro(Symmetric, vtkTypeBool);
162   vtkBooleanMacro(Symmetric, vtkTypeBool);
163   ///@}
164 
165   ///@{
166   /**
167    * Set/Get the distance, along x, from the origin to the end of the
168    * source glyph. It is used to draw the symmetric glyphs.
169    */
170   vtkSetMacro(Length, double);
171   vtkGetMacro(Length, double);
172   ///@}
173 
174   ///@{
175   /**
176    * Turn on/off extraction of eigenvalues from tensor.
177    */
178   vtkSetMacro(ExtractEigenvalues, vtkTypeBool);
179   vtkBooleanMacro(ExtractEigenvalues, vtkTypeBool);
180   vtkGetMacro(ExtractEigenvalues, vtkTypeBool);
181   ///@}
182 
183   ///@{
184   /**
185    * Turn on/off coloring of glyph with input scalar data or
186    * eigenvalues. If false, or input scalar data not present, then the
187    * scalars from the source object are passed through the filter.
188    */
189   vtkSetMacro(ColorGlyphs, vtkTypeBool);
190   vtkGetMacro(ColorGlyphs, vtkTypeBool);
191   vtkBooleanMacro(ColorGlyphs, vtkTypeBool);
192   ///@}
193 
194   enum
195   {
196     COLOR_BY_SCALARS,
197     COLOR_BY_EIGENVALUES
198   };
199 
200   ///@{
201   /**
202    * Set the color mode to be used for the glyphs.  This can be set to
203    * use the input scalars (default) or to use the eigenvalues at the
204    * point.  If ThreeGlyphs is set and the eigenvalues are chosen for
205    * coloring then each glyph is colored by the corresponding
206    * eigenvalue and if not set the color corresponding to the largest
207    * eigenvalue is chosen.  The recognized values are:
208    * COLOR_BY_SCALARS = 0 (default)
209    * COLOR_BY_EIGENVALUES = 1
210    */
211   vtkSetClampMacro(ColorMode, int, COLOR_BY_SCALARS, COLOR_BY_EIGENVALUES);
212   vtkGetMacro(ColorMode, int);
SetColorModeToScalars()213   void SetColorModeToScalars() { this->SetColorMode(COLOR_BY_SCALARS); }
SetColorModeToEigenvalues()214   void SetColorModeToEigenvalues() { this->SetColorMode(COLOR_BY_EIGENVALUES); }
215   ///@}
216 
217   ///@{
218   /**
219    * Turn on/off scalar clamping. If scalar clamping is on, the ivar
220    * MaxScaleFactor is used to control the maximum scale factor. (This is
221    * useful to prevent uncontrolled scaling near singularities.)
222    */
223   vtkSetMacro(ClampScaling, vtkTypeBool);
224   vtkGetMacro(ClampScaling, vtkTypeBool);
225   vtkBooleanMacro(ClampScaling, vtkTypeBool);
226   ///@}
227 
228   ///@{
229   /**
230    * Set/Get the maximum allowable scale factor. This value is compared to the
231    * combination of the scale factor times the eigenvalue. If less, the scale
232    * factor is reset to the MaxScaleFactor. The boolean ClampScaling has to
233    * be "on" for this to work.
234    */
235   vtkSetMacro(MaxScaleFactor, double);
236   vtkGetMacro(MaxScaleFactor, double);
237   ///@}
238 
239 protected:
240   vtkTensorGlyph();
241   ~vtkTensorGlyph() override;
242 
243   int RequestUpdateExtent(vtkInformation*, vtkInformationVector**, vtkInformationVector*) override;
244   int RequestData(vtkInformation*, vtkInformationVector**, vtkInformationVector*) override;
245   int FillInputPortInformation(int port, vtkInformation* info) override;
246 
247   vtkTypeBool Scaling;            // Determine whether scaling of geometry is performed
248   double ScaleFactor;             // Scale factor to use to scale geometry
249   vtkTypeBool ExtractEigenvalues; // Boolean controls eigenfunction extraction
250   vtkTypeBool ColorGlyphs;        // Boolean controls coloring with input scalar data
251   int ColorMode;                  // The coloring mode to use for the glyphs.
252   vtkTypeBool ClampScaling;       // Boolean controls whether scaling is clamped.
253   double MaxScaleFactor;          // Maximum scale factor (ScaleFactor*eigenvalue)
254   vtkTypeBool ThreeGlyphs;        // Boolean controls drawing 1 or 3 glyphs
255   vtkTypeBool Symmetric;          // Boolean controls drawing a "mirror" of each glyph
256   double Length;                  // Distance, in x, from the origin to the end of the glyph
257 private:
258   vtkTensorGlyph(const vtkTensorGlyph&) = delete;
259   void operator=(const vtkTensorGlyph&) = delete;
260 };
261 
262 #endif
263