1 /*=========================================================================
3 Program: Visualization Toolkit
4 Module: $RCSfile: vtkStreamer.h,v $
6 Date: $Date: 2002/02/01 06:35:50 $
7 Version: $Revision: 1.1.1.1 $
10 Copyright (c) 1993-1998 Ken Martin, Will Schroeder, Bill Lorensen.
12 This software is copyrighted by Ken Martin, Will Schroeder and Bill Lorensen.
13 The following terms apply to all files associated with the software unless
14 explicitly disclaimed in individual files. This copyright specifically does
15 not apply to the related textbook "The Visualization Toolkit" ISBN
16 013199837-4 published by Prentice Hall which is covered by its own copyright.
18 The authors hereby grant permission to use, copy, and distribute this
19 software and its documentation for any purpose, provided that existing
20 copyright notices are retained in all copies and that this notice is included
21 verbatim in any distributions. Additionally, the authors grant permission to
22 modify this software and its documentation for any purpose, provided that
23 such modifications are not distributed without the explicit consent of the
24 authors and that existing copyright notices are retained in all copies. Some
25 of the algorithms implemented by this software are patented, observe all
26 applicable patent law.
28 IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR
29 DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
30 OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF,
31 EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33 THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING,
34 BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
35 PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN
36 "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE
37 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
40 =========================================================================*/
41 // .NAME vtkStreamer - abstract object implements integration of massless particle through vector field
42 // .SECTION Description
43 // vtkStreamer is a filter that integrates a massless particle through a vector
44 // field. The integration is performed using second order Runge-Kutta method.
45 // vtkStreamer often serves as a base class for other classes that perform
46 // numerical integration through a vector field (e.g., vtkStreamLine).
48 // Note that vtkStreamer can integrate both forward and backward in time,
49 // or in both directions. The length of the streamer is controlled by
50 // specifying an elapsed time. (The elapsed time is the time each particle
51 // travels.) Otherwise, the integration terminates after exiting the dataset or
52 // if the particle speed is reduced to a value less than the terminal speed.
54 // vtkStreamer integrates through any type of dataset. As a result, if the
55 // dataset contains 2D cells such as polygons or triangles, the integration is
56 // constrained to lie on the surface defined by the 2D cells.
58 // The starting point of streamers may be defined in three different ways.
59 // Starting from global x-y-z "position" allows you to start a single streamer
60 // at a specified x-y-z coordinate. Starting from "location" allows you to
61 // start at a specified cell, subId, and parametric coordinate. Finally, you
62 // may specify a source object to start multiple streamers. If you start
63 // streamers using a source object, for each point in the source that is
64 // inside the dataset a streamer is created.
66 // vtkStreamer implements the integration process in the Integrate() method.
67 // Because vtkStreamer does not implement the Execute() method that its
68 // superclass (i.e., Filter) requires, it is an abstract class. Its subclasses
69 // implement the execute method and use the Integrate() method, and then build
70 // their own representation of the integration path (i.e., lines, dashed
71 // lines, points, etc.).
73 // vtkStreamLine vtkDashedStreamLine vtkStreamPoints
75 #ifndef __vtkStreamer_h
76 #define __vtkStreamer_h
78 #include "vtkDataSetToPolyDataFilter.h"
80 #define VTK_INTEGRATE_FORWARD 0
81 #define VTK_INTEGRATE_BACKWARD 1
82 #define VTK_INTEGRATE_BOTH_DIRECTIONS 2
84 typedef struct _vtkStreamPoint {
85 float x[3]; // position
87 int subId; // cell sub id
88 float p[3]; // parametric coords in cell
89 float v[3]; // velocity
90 float speed; // velocity norm
91 float s; // scalar value
92 float t; // time travelled so far
93 float d; // distance travelled so far
94 float w[3]; // vorticity (if vorticity is computed)
95 float n[3]; // normal (if vorticity is computed)
99 // Special classes for manipulating data
101 //BTX - begin tcl exclude
103 class vtkStreamArray { //;prevent man page generation
106 ~vtkStreamArray() {if (this->Array) delete [] this->Array;};
107 int GetNumberOfPoints() {return this->MaxId + 1;};
108 vtkStreamPoint *GetStreamPoint(int i) {return this->Array + i;};
109 vtkStreamPoint *InsertNextStreamPoint()
111 if ( ++this->MaxId >= this->Size ) this->Resize(this->MaxId);
112 return this->Array + this->MaxId;
114 vtkStreamPoint *Resize(int sz); //reallocates data
115 void Reset() {this->MaxId = -1;};
117 vtkStreamPoint *Array; // pointer to data
118 int MaxId; // maximum index inserted thus far
119 int Size; // allocated size of data
120 int Extend; // grow array by this amount
121 float Direction; // integration direction
126 class VTK_EXPORT vtkStreamer : public vtkDataSetToPolyDataFilter
131 static vtkStreamer *New() {return new vtkStreamer;};
132 const char *GetClassName() {return "vtkStreamer";};
133 void PrintSelf(ostream& os, vtkIndent indent);
135 void SetStartLocation(int cellId, int subId, float pcoords[3]);
136 void SetStartLocation(int cellId, int subId, float r, float s, float t);
137 int GetStartLocation(int& subId, float pcoords[3]);
139 void SetStartPosition(float x[3]);
140 void SetStartPosition(float x, float y, float z);
141 float *GetStartPosition();
146 // Specify the source object used to generate starting points.
147 vtkSetObjectMacro(Source,vtkDataSet);
148 vtkGetObjectMacro(Source,vtkDataSet);
151 // Specify the maximum length of the Streamer expressed in elapsed time.
152 vtkSetClampMacro(MaximumPropagationTime,float,0.0,VTK_LARGE_FLOAT);
153 vtkGetMacro(MaximumPropagationTime,float);
156 // Specify the direction in which to integrate the Streamer.
157 vtkSetClampMacro(IntegrationDirection,int,
158 VTK_INTEGRATE_FORWARD,VTK_INTEGRATE_BOTH_DIRECTIONS);
159 vtkGetMacro(IntegrationDirection,int);
160 void SetIntegrationDirectionToForward()
161 {this->SetIntegrationDirection(VTK_INTEGRATE_FORWARD);};
162 void SetIntegrationDirectionToBackward()
163 {this->SetIntegrationDirection(VTK_INTEGRATE_BACKWARD);};
164 void SetIntegrationDirectionToIntegrateBothDirections()
165 {this->SetIntegrationDirection(VTK_INTEGRATE_BOTH_DIRECTIONS);};
166 char *GetIntegrationDirectionAsString();
169 // Specify a nominal integration step size (expressed as a fraction of
170 // the size of each cell).
171 vtkSetClampMacro(IntegrationStepLength,float,0.001,0.5);
172 vtkGetMacro(IntegrationStepLength,float);
175 // Turn on/off the creation of scalar data from velocity magnitude. If off,
176 // and input dataset has scalars, input dataset scalars are used.
177 vtkSetMacro(SpeedScalars,int);
178 vtkGetMacro(SpeedScalars,int);
179 vtkBooleanMacro(SpeedScalars,int);
182 // Set/get terminal speed (i.e., speed is velocity magnitude). Terminal
183 // speed is speed at which streamer will terminate propagation.
184 vtkSetClampMacro(TerminalSpeed,float,0.0,VTK_LARGE_FLOAT);
185 vtkGetMacro(TerminalSpeed,float);
188 // Turn on/off the computation of vorticity. Vorticity is an indication of
189 // the rotation of the flow. In combination with vtkStreamLine and
190 // vtkTubeFilter can be used to create rotated tubes.
191 vtkSetMacro(Vorticity,int);
192 vtkGetMacro(Vorticity,int);
193 vtkBooleanMacro(Vorticity,int);
199 // Special method for computing streamer vorticity
200 void ComputeVorticity();
202 // Controls where streamlines start from (either position or location).
205 // Starting from cell location
208 float StartPCoords[3];
210 // starting from global x-y-z position
211 float StartPosition[3];
213 //points used to seed streamlines
217 vtkStreamArray *Streamers;
218 int NumberOfStreamers;
220 // length of Streamer is generated by time, or by MaximumSteps
221 float MaximumPropagationTime;
223 // integration direction
224 int IntegrationDirection;
226 // the length (fraction of cell size) of integration steps
227 float IntegrationStepLength;
229 // boolean controls whether vorticity is computed
232 // terminal propagation speed
235 // boolean controls whether data scalars or velocity magnitude are used
240 // Return the integration direction as a character string.
241 inline char *vtkStreamer::GetIntegrationDirectionAsString(void)
243 if ( this->IntegrationDirection == VTK_INTEGRATE_FORWARD )
245 return "IntegrateForward";
247 else if ( this->IntegrationDirection == VTK_INTEGRATE_BACKWARD )
249 return "IntegrateBackward";
253 return "IntegrateBothDirections";