I686LINUX/util/I686LINUX/include/vtk/vtkStreamTracer.h

   1 /*=========================================================================
   2
   3   Program:   Visualization Toolkit
   4   Module:    $RCSfile: vtkStreamTracer.h,v $
   5   Language:  C++
   6   Date:      $Date: 2003/01/09 19:21:05 $
   7   Version:   $Revision: 1.13 $
   8
   9   Copyright (c) 1993-2002 Ken Martin, Will Schroeder, Bill Lorensen
  10   All rights reserved.
  11   See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
  12
  13      This software is distributed WITHOUT ANY WARRANTY; without even
  14      the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15      PURPOSE.  See the above copyright notice for more information.
  16
  17 =========================================================================*/
  18 // .NAME vtkStreamTracer - Streamline generator
  19 // .SECTION Description
  20 // vtkStreamTracer is a filter that integrates a vector field to generate
  21 // streamlines. The integration is performed using the provided integrator.
  22 // The default is second order Runge-Kutta.
  23 //
  24 // vtkStreamTracer generate polylines as output. Each cell (polyline)
  25 // corresponds to one streamline. The values associated with each streamline
  26 // are stored in the cell data whereas the values associated with points
  27 // are stored in point data.
  28 //
  29 // Note that vtkStreamTracer can integrate both forward and backward.
  30 // The length of the streamline is controlled by specifying either
  31 // a maximum value in the units of length, cell length or elapsed time
  32 // (the elapsed time is the time each particle would have traveled if
  33 // flow were steady). Otherwise, the integration terminates after exiting
  34 // the dataset or if the particle speed is reduced to a value less than
  35 // the terminal speed or when a maximum number of steps is reached.
  36 // The reason for the termination is stored in a cell array named
  37 // ReasonForTermination.
  38 //
  39 // The quality of integration can be controlled by setting integration
  40 // step (InitialIntegrationStep) and in the case of adaptive solvers
  41 // the maximum error, the minimum integration step and the maximum
  42 // integration step. All of these can have units of length, cell length
  43 // or elapsed time.
  44 //
  45 // The integration time, vorticity, rotation and angular velocity
  46 // are stored in point arrays named "IntegrationTime", "Vorticity",
  47 // "Rotation" and "AngularVelocity" respectively (vorticity, rotation
  48 // and angular velocity are computed only when ComputeVorticity is on).
  49 // All point attributes in the source data set are interpolated on the
  50 // new streamline points.
  51 //
  52 // vtkStreamTracer integrates through any type of dataset. As a result, if the
  53 // dataset contains 2D cells such as polygons or triangles, the integration is
  54 // constrained to lie on the surface defined by the 2D cells.
  55 //
  56 // The starting point of traces may be defined in two different ways.
  57 // Starting from global x-y-z "position" allows you to start a single trace
  58 // at a specified x-y-z coordinate. If you specify a source object,
  59 // a trace will be generated for each point in the source that is
  60 // inside the dataset.
  61 //
  62 // .SECTION See Also
  63 // vtkRibbonFilter vtkRuledSurfaceFilter vtkInitialValueProblemSolver
  64 // vtkRungeKutta2 vtkRungeKutta4 vtkRungeKutta45
  65
  66 #ifndef __vtkStreamTracer_h
  67 #define __vtkStreamTracer_h
  68
  69 #include "vtkDataSetToPolyDataFilter.h"
  70
  71 #include "vtkInitialValueProblemSolver.h" // Needed for constants
  72
  73 class vtkDataArray;
  74 class vtkFloatArray;
  75 class vtkGenericCell;
  76 class vtkIdList;
  77 class vtkIntArray;
  78 class vtkInterpolatedVelocityField;
  79
  80 class VTK_GRAPHICS_EXPORT vtkStreamTracer : public vtkDataSetToPolyDataFilter
  81 {
  82 public:
  83   vtkTypeRevisionMacro(vtkStreamTracer,vtkDataSetToPolyDataFilter);
  84   void PrintSelf(ostream& os, vtkIndent indent);
  85
  86   // Description:
  87   // Construct object to start from position (0,0,0), integrate forward,
  88   // terminal speed 1.0E-12, vorticity computation on, integration
  89   // step length 0.5 (unit cell length), maximum number of steps 2000,
  90   // using 2nd order Runge Kutta and maximum propagation 1.0 (unit length).
  91   static vtkStreamTracer *New();
  92
  93   // Description:
  94   // Specify the start of the streamline in the global coordinate
  95   // system. Search must be performed to find initial cell to start
  96   // integration from.
  97   vtkSetVector3Macro(StartPosition, float);
  98   vtkGetVector3Macro(StartPosition, float);
  99
 100   // Description:
 101   // Specify the source object used to generate starting points.
 102   void SetSource(vtkDataSet *source);
 103   vtkDataSet *GetSource();
 104
 105 //BTX
 106   enum Units
 107   {
 108     TIME_UNIT,
 109     LENGTH_UNIT,
 110     CELL_LENGTH_UNIT
 111   };
 112
 113   enum Solvers
 114   {
 115     RUNGE_KUTTA2,
 116     RUNGE_KUTTA4,
 117     RUNGE_KUTTA45,
 118     NONE,
 119     UNKNOWN
 120   };
 121
 122   enum ReasonForTermination
 123   {
 124     OUT_OF_DOMAIN = vtkInitialValueProblemSolver::OUT_OF_DOMAIN,
 125     NOT_INITIALIZED = vtkInitialValueProblemSolver::NOT_INITIALIZED ,
 126     UNEXPECTED_VALUE = vtkInitialValueProblemSolver::UNEXPECTED_VALUE,
 127     OUT_OF_TIME = 4,
 128     OUT_OF_STEPS = 5,
 129     STAGNATION = 6
 130   };
 131 //ETX
 132
 133   // Description:
 134   // Set/get the integrator type to be used in the stream line
 135   // calculation. The object passed is not actually used but
 136   // is cloned with NewInstance in the process of integration
 137   // (prototype pattern). The default is 2nd order Runge Kutta.
 138   // The integrator can also be changed using SetIntegratorType.
 139   // The recognized solvers are:
 140   // RUNGE_KUTTA2  = 0
 141   // RUNGE_KUTTA4  = 1
 142   // RUNGE_KUTTA45 = 2
 143   void SetIntegrator(vtkInitialValueProblemSolver *);
 144   vtkGetObjectMacro ( Integrator, vtkInitialValueProblemSolver );
 145   void SetIntegratorType(int type);
 146   int GetIntegratorType();
 147   void SetIntegratorTypeToRungeKutta2()
 148     {this->SetIntegratorType(RUNGE_KUTTA2);};
 149   void SetIntegratorTypeToRungeKutta4()
 150     {this->SetIntegratorType(RUNGE_KUTTA4);};
 151   void SetIntegratorTypeToRungeKutta45()
 152     {this->SetIntegratorType(RUNGE_KUTTA45);};
 153
 154   // Description:
 155   // Specify the maximum length of the streamlines expressed in
 156   // one of the:
 157   // TIME_UNIT        = 0
 158   // LENGTH_UNIT      = 1
 159   // CELL_LENGTH_UNIT = 2
 160   void SetMaximumPropagation(int unit, float max);
 161   void SetMaximumPropagation(float max);
 162   void SetMaximumPropagationUnit(int unit);
 163   int GetMaximumPropagationUnit();
 164   float GetMaximumPropagation();
 165   void SetMaximumPropagationUnitToTimeUnit()
 166     {this->SetMaximumPropagationUnit(TIME_UNIT);};
 167   void SetMaximumPropagationUnitToLengthUnit()
 168     {this->SetMaximumPropagationUnit(LENGTH_UNIT);};
 169   void SetMaximumPropagationUnitToCellLengthUnit()
 170     {this->SetMaximumPropagationUnit(CELL_LENGTH_UNIT);};
 171
 172   // Description:
 173   // Specify the minimum step used in the integration expressed in
 174   // one of the:
 175   // TIME_UNIT        = 0
 176   // LENGTH_UNIT      = 1
 177   // CELL_LENGTH_UNIT = 2
 178   // Only valid when using adaptive integrators.
 179   void SetMinimumIntegrationStep(int unit, float step);
 180   void SetMinimumIntegrationStepUnit(int unit);
 181   void SetMinimumIntegrationStep(float step);
 182   int GetMinimumIntegrationStepUnit();
 183   float GetMinimumIntegrationStep();
 184   void SetMinimumIntegrationStepUnitToTimeUnit()
 185     {this->SetMinimumIntegrationStepUnit(TIME_UNIT);};
 186   void SetMinimumIntegrationStepUnitToLengthUnit()
 187     {this->SetMinimumIntegrationStepUnit(LENGTH_UNIT);};
 188   void SetMinimumIntegrationStepUnitToCellLengthUnit()
 189     {this->SetMinimumIntegrationStepUnit(CELL_LENGTH_UNIT);};
 190
 191   // Description:
 192   // Specify the maximum step used in the integration expressed in
 193   // one of the:
 194   // TIME_UNIT        = 0
 195   // LENGTH_UNIT      = 1
 196   // CELL_LENGTH_UNIT = 2
 197   // Only valid when using adaptive integrators.
 198   void SetMaximumIntegrationStep(int unit, float step);
 199   void SetMaximumIntegrationStepUnit(int unit);
 200   void SetMaximumIntegrationStep(float step);
 201   int GetMaximumIntegrationStepUnit();
 202   float GetMaximumIntegrationStep();
 203   void SetMaximumIntegrationStepUnitToTimeUnit()
 204     {this->SetMaximumIntegrationStepUnit(TIME_UNIT);};
 205   void SetMaximumIntegrationStepUnitToLengthUnit()
 206     {this->SetMaximumIntegrationStepUnit(LENGTH_UNIT);};
 207   void SetMaximumIntegrationStepUnitToCellLengthUnit()
 208     {this->SetMaximumIntegrationStepUnit(CELL_LENGTH_UNIT);};
 209
 210   // Description:
 211   // Specify the initial step used in the integration expressed in
 212   // one of the:
 213   // TIME_UNIT        = 0
 214   // LENGTH_UNIT      = 1
 215   // CELL_LENGTH_UNIT = 2
 216   // If the integrator is not adaptive, this is the actual
 217   // step used.
 218   void SetInitialIntegrationStep(int unit, float step);
 219   void SetInitialIntegrationStepUnit(int unit);
 220   void SetInitialIntegrationStep(float step);
 221   int GetInitialIntegrationStepUnit();
 222   float GetInitialIntegrationStep();
 223   void SetInitialIntegrationStepUnitToTimeUnit()
 224     {this->SetInitialIntegrationStepUnit(TIME_UNIT);};
 225   void SetInitialIntegrationStepUnitToLengthUnit()
 226     {this->SetInitialIntegrationStepUnit(LENGTH_UNIT);};
 227   void SetInitialIntegrationStepUnitToCellLengthUnit()
 228     {this->SetInitialIntegrationStepUnit(CELL_LENGTH_UNIT);};
 229
 230   // Description
 231   // Specify the maximum error in the integration. This value
 232   // is passed to the integrator. Therefore, it's meaning depends
 233   // on the integrator used.
 234   vtkSetMacro(MaximumError, float);
 235   vtkGetMacro(MaximumError, float);
 236
 237   // Description
 238   // Specify the maximum number of steps used in the integration.
 239   vtkSetMacro(MaximumNumberOfSteps, vtkIdType);
 240   vtkGetMacro(MaximumNumberOfSteps, vtkIdType);
 241
 242   // Description
 243   // If at any point, the speed is below this value, the integration
 244   // is terminated.
 245   vtkSetMacro(TerminalSpeed, float);
 246   vtkGetMacro(TerminalSpeed, float);
 247
 248 //BTX
 249   enum
 250   {
 251     FORWARD,
 252     BACKWARD,
 253     BOTH
 254   };
 255 //ETX
 256
 257   // Description:
 258   // Specify whether the streamtrace will be generated in the
 259   // upstream or downstream direction.
 260   vtkSetClampMacro(IntegrationDirection, int, FORWARD, BOTH);
 261   vtkGetMacro(IntegrationDirection, int);
 262   void SetIntegrationDirectionToForward()
 263     {this->SetIntegrationDirection(FORWARD);};
 264   void SetIntegrationDirectionToBackward()
 265     {this->SetIntegrationDirection(BACKWARD);};
 266   void SetIntegrationDirectionToBoth()
 267     {this->SetIntegrationDirection(BOTH);};
 268
 269   // Description
 270   // Turn on/off calculation of vorticity at streamline points
 271   // (necessary for generating proper streamribbons using the
 272   // vtkRibbonFilter.
 273   vtkSetMacro(ComputeVorticity, int);
 274   vtkGetMacro(ComputeVorticity, int);
 275   vtkBooleanMacro(ComputeVorticity, int);
 276
 277   // Description
 278   // This can be used to scale the rate with which the streamribbons
 279   // twist. The default is 1.
 280   vtkSetMacro(RotationScale, float);
 281   vtkGetMacro(RotationScale, float);
 282
 283   // Description:
 284   // Add a dataset to the list inputs
 285   void AddInput(vtkDataSet *in);
 286
 287 protected:
 288
 289   vtkStreamTracer();
 290   ~vtkStreamTracer();
 291
 292   // hide the superclass' AddInput() from the user and the compiler
 293   void AddInput(vtkDataObject *)
 294     { vtkErrorMacro( << "AddInput() must be called with a vtkDataSet not a vtkDataObject."); };
 295
 296   void Execute();
 297   void CalculateVorticity( vtkGenericCell* cell, float pcoords[3],
 298                            vtkFloatArray* cellVectors, float vorticity[3] );
 299   void Integrate(vtkPolyData* output,
 300                  vtkDataArray* seedSource,
 301                  vtkIdList* seedIds,
 302                  vtkIntArray* integrationDirections,
 303                  float lastPoint[3]);
 304   int CheckInputs(vtkInterpolatedVelocityField*& func,
 305                   int* maxCellSize);
 306
 307   vtkSetStringMacro(InputVectorsSelection);
 308   char *InputVectorsSelection;
 309
 310
 311   // starting from global x-y-z position
 312   float StartPosition[3];
 313
 314   static const float EPSILON;
 315   float TerminalSpeed;
 316
 317 //BTX
 318   struct IntervalInformation
 319   {
 320     float Interval;
 321     int Unit;
 322   };
 323
 324   IntervalInformation MaximumPropagation;
 325   IntervalInformation MinimumIntegrationStep;
 326   IntervalInformation MaximumIntegrationStep;
 327   IntervalInformation InitialIntegrationStep;
 328
 329   void SetIntervalInformation(int unit, float interval,
 330                               IntervalInformation& currentValues);
 331   void SetIntervalInformation(int unit,IntervalInformation& currentValues);
 332   static float ConvertToTime(IntervalInformation& interval,
 333                              float cellLength, float speed);
 334   static float ConvertToLength(IntervalInformation& interval,
 335                                float cellLength, float speed);
 336   static float ConvertToCellLength(IntervalInformation& interval,
 337                                    float cellLength, float speed);
 338   static float ConvertToUnit(IntervalInformation& interval, int unit,
 339                              float cellLength, float speed);
 340   void ConvertIntervals(float& step, float& minStep, float& maxStep,
 341                         int direction, float cellLength, float speed);
 342 //ETX
 343
 344   void InitializeSeeds(vtkDataArray*& seeds,
 345                        vtkIdList*& seedIds,
 346                        vtkIntArray*& integrationDirections);
 347
 348   int IntegrationDirection;
 349
 350   // Prototype showing the integrator type to be set by the user.
 351   vtkInitialValueProblemSolver* Integrator;
 352
 353   float MaximumError;
 354   vtkIdType MaximumNumberOfSteps;
 355
 356   int ComputeVorticity;
 357   float RotationScale;
 358
 359 private:
 360   vtkStreamTracer(const vtkStreamTracer&);  // Not implemented.
 361   void operator=(const vtkStreamTracer&);  // Not implemented.
 362 };
 363
 364
 365 #endif
 366
 367