VTK  9.3.0
vtkStreamTracer.h
Go to the documentation of this file.
1 // SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen
2 // SPDX-License-Identifier: BSD-3-Clause
91 #ifndef vtkStreamTracer_h
92 #define vtkStreamTracer_h
93 
94 #include "vtkFiltersFlowPathsModule.h" // For export macro
95 #include "vtkPolyDataAlgorithm.h"
96 
97 #include "vtkDataSetAttributesFieldList.h" // Needed to identify common data arrays
98 #include "vtkInitialValueProblemSolver.h" // Needed for constants
99 
100 VTK_ABI_NAMESPACE_BEGIN
102 class vtkCompositeDataSet;
103 class vtkDataArray;
105 class vtkDoubleArray;
106 class vtkExecutive;
107 class vtkGenericCell;
108 class vtkIdList;
109 class vtkIntArray;
110 class vtkPoints;
111 
112 VTK_ABI_NAMESPACE_END
113 #include <vector> // for std::vector
114 
115 // Helper struct to convert between different length scales.
116 VTK_ABI_NAMESPACE_BEGIN
117 struct VTKFILTERSFLOWPATHS_EXPORT vtkIntervalInformation
118 {
119  double Interval;
120  int Unit;
121 
122  static double ConvertToLength(double interval, int unit, double cellLength);
123  static double ConvertToLength(vtkIntervalInformation& interval, double cellLength);
124 };
125 
137  void* clientdata, vtkPoints* points, vtkDataArray* velocity, int integrationDirection);
138 
139 class VTKFILTERSFLOWPATHS_EXPORT vtkStreamTracer : public vtkPolyDataAlgorithm
140 {
141 public:
149  static vtkStreamTracer* New();
150 
152 
156  void PrintSelf(ostream& os, vtkIndent indent) override;
158 
160 
165  vtkSetVector3Macro(StartPosition, double);
166  vtkGetVector3Macro(StartPosition, double);
168 
170 
179 
186 
187  // The previously-supported TIME_UNIT is excluded in this current
188  // enumeration definition because the underlying step size is ALWAYS in
189  // arc length unit (LENGTH_UNIT) while the 'real' time interval (virtual
190  // for steady flows) that a particle actually takes to trave in a single
191  // step is obtained by dividing the arc length by the LOCAL speed. The
192  // overall elapsed time (i.e., the life span) of the particle is the sum
193  // of those individual step-wise time intervals. The arc-length-to-time
194  // conversion only occurs for vorticity computation and for generating a
195  // point data array named 'IntegrationTime'.
196  enum Units
197  {
198  LENGTH_UNIT = 1,
199  CELL_LENGTH_UNIT = 2
200  };
201 
202  enum Solvers
203  {
208  UNKNOWN
209  };
210 
212  {
216  OUT_OF_LENGTH = 4,
217  OUT_OF_STEPS = 5,
218  STAGNATION = 6,
219  FIXED_REASONS_FOR_TERMINATION_COUNT
220  };
221 
223 
234  vtkGetObjectMacro(Integrator, vtkInitialValueProblemSolver);
237  void SetIntegratorTypeToRungeKutta2() { this->SetIntegratorType(RUNGE_KUTTA2); }
238  void SetIntegratorTypeToRungeKutta4() { this->SetIntegratorType(RUNGE_KUTTA4); }
239  void SetIntegratorTypeToRungeKutta45() { this->SetIntegratorType(RUNGE_KUTTA45); }
241 
252 
260 
262 
265  vtkSetMacro(MaximumPropagation, double);
266  vtkGetMacro(MaximumPropagation, double);
268 
275  void SetIntegrationStepUnit(int unit);
276  int GetIntegrationStepUnit() { return this->IntegrationStepUnit; }
277 
279 
286  vtkSetMacro(InitialIntegrationStep, double);
287  vtkGetMacro(InitialIntegrationStep, double);
289 
291 
297  vtkSetMacro(MinimumIntegrationStep, double);
298  vtkGetMacro(MinimumIntegrationStep, double);
300 
302 
308  vtkSetMacro(MaximumIntegrationStep, double);
309  vtkGetMacro(MaximumIntegrationStep, double);
311 
313 
316  vtkSetMacro(MaximumError, double);
317  vtkGetMacro(MaximumError, double);
319 
321 
329  vtkSetMacro(MaximumNumberOfSteps, vtkIdType);
330  vtkGetMacro(MaximumNumberOfSteps, vtkIdType);
332 
334 
338  vtkSetMacro(TerminalSpeed, double);
339  vtkGetMacro(TerminalSpeed, double);
341 
343 
346  vtkGetMacro(SurfaceStreamlines, bool);
347  vtkSetMacro(SurfaceStreamlines, bool);
348  vtkBooleanMacro(SurfaceStreamlines, bool);
350 
351  enum
352  {
355  BOTH
356  };
357 
358  enum
359  {
361  INTERPOLATOR_WITH_CELL_LOCATOR
362  };
363 
365 
372  vtkSetClampMacro(IntegrationDirection, int, FORWARD, BOTH);
373  vtkGetMacro(IntegrationDirection, int);
374  void SetIntegrationDirectionToForward() { this->SetIntegrationDirection(FORWARD); }
375  void SetIntegrationDirectionToBackward() { this->SetIntegrationDirection(BACKWARD); }
376  void SetIntegrationDirectionToBoth() { this->SetIntegrationDirection(BOTH); }
378 
380 
385  vtkSetMacro(ComputeVorticity, bool);
386  vtkGetMacro(ComputeVorticity, bool);
388 
390 
394  vtkSetMacro(RotationScale, double);
395  vtkGetMacro(RotationScale, double);
397 
408 
418  void SetInterpolatorType(int interpType);
419 
421 
425  vtkGetMacro(ForceSerialExecution, bool);
426  vtkSetMacro(ForceSerialExecution, bool);
427  vtkBooleanMacro(ForceSerialExecution, bool);
429 
439  CustomTerminationCallbackType callback, void* clientdata, int reasonForTermination);
440 
450  double& step, double& minStep, double& maxStep, int direction, double cellLength);
451 
453 
457  void GenerateNormals(vtkPolyData* output, double* firstNormal, const char* vecName);
459  vtkGenericCell* cell, double pcoords[3], vtkDoubleArray* cellVectors, double vorticity[3]);
461 
463 
473  vtkSetMacro(UseLocalSeedSource, bool);
474  vtkGetMacro(UseLocalSeedSource, bool);
475  vtkBooleanMacro(UseLocalSeedSource, bool);
477 
478 protected:
480  ~vtkStreamTracer() override;
481 
482  // Create a default executive.
484 
485  // hide the superclass' AddInput() from the user and the compiler
487  {
488  vtkErrorMacro(<< "AddInput() must be called with a vtkDataSet not a vtkDataObject.");
489  }
490 
493 
494  void Integrate(vtkPointData* inputData, vtkPolyData* output, vtkDataArray* seedSource,
495  vtkIdList* seedIds, vtkIntArray* integrationDirections,
496  vtkAbstractInterpolatedVelocityField* func, int maxCellSize, int vecType,
497  const char* vecFieldName, double& propagation, vtkIdType& numSteps, double& integrationTime,
498  std::vector<CustomTerminationCallbackType>& customTerminationCallback,
499  std::vector<void*>& customTerminationClientData, std::vector<int>& customReasonForTermination);
500 
501  double SimpleIntegrate(double seed[3], double lastPoint[3], double stepSize,
503  int CheckInputs(vtkAbstractInterpolatedVelocityField*& func, int* maxCellSize);
504 
506 
507  // starting from global x-y-z position
508  double StartPosition[3];
509 
510  static const double EPSILON;
512 
513  // Used by subclasses, leave alone
515 
520 
521  int SetupOutput(vtkInformation* inInfo, vtkInformation* outInfo);
522  void InitializeSeeds(vtkDataArray*& seeds, vtkIdList*& seedIds,
523  vtkIntArray*& integrationDirections, vtkDataSet* source);
524 
527 
528  // Prototype showing the integrator type to be set by the user.
530 
531  double MaximumError;
533 
536 
537  // Compute streamlines only on surface.
539 
541 
542  // These are used to manage complex input types such as
543  // multiblock / composite datasets. Basically the filter input is
544  // converted to a composite dataset, and the point data attributes
545  // are intersected to produce a common set of output data arrays.
546  vtkCompositeDataSet* InputData; // convert input data to composite dataset
547  vtkDataSetAttributesFieldList InputPD; // intersect attributes of all datasets
548  bool
549  HasMatchingPointAttributes; // does the point data in the multiblocks have the same attributes?
550 
551  // Control execution as serial or threaded
553  bool SerialExecution; // internal use to combine information
554 
555  std::vector<CustomTerminationCallbackType> CustomTerminationCallback;
556  std::vector<void*> CustomTerminationClientData;
557  std::vector<int> CustomReasonForTermination;
558 
559  // Only relevant for this derived parallel version of vtkStreamTracer,
560  // but needs to be defined in this class to have a uniform interface
561  // between this class and the parallel override vtkPStreamTracer
563 
564  friend class PStreamTracerUtils;
565 
566 private:
567  vtkStreamTracer(const vtkStreamTracer&) = delete;
568  void operator=(const vtkStreamTracer&) = delete;
569 };
570 
571 VTK_ABI_NAMESPACE_END
572 #endif
An abstract class for obtaining the interpolated velocity values at a point.
Proxy object to connect input/output ports.
abstract superclass for composite (multi-block or AMR) datasets
abstract superclass for arrays of numeric data
Definition: vtkDataArray.h:54
general representation of visualization data
Definition: vtkDataObject.h:64
helps manage arrays from multiple vtkDataSetAttributes.
represent and manipulate attribute data in a dataset
abstract class to specify dataset behavior
Definition: vtkDataSet.h:62
dynamic, self-adjusting array of double
Superclass for all pipeline executives in VTK.
Definition: vtkExecutive.h:48
provides thread-safe access to cells
list of point or cell ids
Definition: vtkIdList.h:32
a simple class to control print indentation
Definition: vtkIndent.h:38
Store zero or more vtkInformation instances.
Store vtkAlgorithm input/output information.
Integrate a set of ordinary differential equations (initial value problem) in time.
dynamic, self-adjusting array of int
Definition: vtkIntArray.h:44
represent and manipulate point attribute data
Definition: vtkPointData.h:39
represent and manipulate 3D points
Definition: vtkPoints.h:38
Superclass for algorithms that produce only polydata as output.
concrete dataset represents vertices, lines, polygons, and triangle strips
Definition: vtkPolyData.h:89
Streamline generator.
void SetIntegratorTypeToRungeKutta45()
Set/get the integrator type to be used for streamline generation.
int FillInputPortInformation(int, vtkInformation *) override
Fill the input port information objects for this algorithm.
int SetupOutput(vtkInformation *inInfo, vtkInformation *outInfo)
std::vector< void * > CustomTerminationClientData
vtkDataSetAttributesFieldList InputPD
void SetSourceData(vtkDataSet *source)
Specify the source object used to generate starting points (seeds).
double InitialIntegrationStep
vtkAbstractInterpolatedVelocityField * InterpolatorPrototype
void SetInterpolatorTypeToCellLocator()
Set the velocity field interpolator type to one that uses a cell locator to perform spatial searching...
void PrintSelf(ostream &os, vtkIndent indent) override
Standard methods to obtain type information and print object state.
void CalculateVorticity(vtkGenericCell *cell, double pcoords[3], vtkDoubleArray *cellVectors, double vorticity[3])
Helper methods to generate normals on streamlines.
double MinimumIntegrationStep
void SetIntegratorTypeToRungeKutta4()
Set/get the integrator type to be used for streamline generation.
vtkDataSet * GetSource()
Specify the source object used to generate starting points (seeds).
@ INTERPOLATOR_WITH_DATASET_POINT_LOCATOR
void SetIntegrator(vtkInitialValueProblemSolver *)
Set/get the integrator type to be used for streamline generation.
void SetSourceConnection(vtkAlgorithmOutput *algOutput)
Specify the source object used to generate starting points (seeds).
std::vector< int > CustomReasonForTermination
int CheckInputs(vtkAbstractInterpolatedVelocityField *&func, int *maxCellSize)
void ConvertIntervals(double &step, double &minStep, double &maxStep, int direction, double cellLength)
The following methods should not be called by the user.
void GenerateNormals(vtkPolyData *output, double *firstNormal, const char *vecName)
Helper methods to generate normals on streamlines.
static const double EPSILON
vtkIdType MaximumNumberOfSteps
void SetIntegrationDirectionToForward()
Specify whether the streamline is integrated in the upstream or downstream direction,...
std::vector< CustomTerminationCallbackType > CustomTerminationCallback
bool HasMatchingPointAttributes
vtkCompositeDataSet * InputData
vtkExecutive * CreateDefaultExecutive() override
Create a default executive.
void SetInterpolatorType(int interpType)
Set the type of the velocity field interpolator to determine whether INTERPOLATOR_WITH_DATASET_POINT_...
double MaximumIntegrationStep
int RequestData(vtkInformation *, vtkInformationVector **, vtkInformationVector *) override
This is called by the superclass.
bool GenerateNormalsInIntegrate
void Integrate(vtkPointData *inputData, vtkPolyData *output, vtkDataArray *seedSource, vtkIdList *seedIds, vtkIntArray *integrationDirections, vtkAbstractInterpolatedVelocityField *func, int maxCellSize, int vecType, const char *vecFieldName, double &propagation, vtkIdType &numSteps, double &integrationTime, std::vector< CustomTerminationCallbackType > &customTerminationCallback, std::vector< void * > &customTerminationClientData, std::vector< int > &customReasonForTermination)
void SetIntegrationDirectionToBackward()
Specify whether the streamline is integrated in the upstream or downstream direction,...
void SetInterpolatorTypeToDataSetPointLocator()
Set the velocity field interpolator type to one that uses a point locator to perform local spatial se...
int GetIntegratorType()
Set/get the integrator type to be used for streamline generation.
void AddCustomTerminationCallback(CustomTerminationCallbackType callback, void *clientdata, int reasonForTermination)
Adds a custom termination callback.
void InitializeSeeds(vtkDataArray *&seeds, vtkIdList *&seedIds, vtkIntArray *&integrationDirections, vtkDataSet *source)
void SetIntegratorTypeToRungeKutta2()
Set/get the integrator type to be used for streamline generation.
static vtkStreamTracer * New()
Construct the object to start from position (0,0,0), with forward integration, terminal speed 1....
void SetIntegrationDirectionToBoth()
Specify whether the streamline is integrated in the upstream or downstream direction,...
double SimpleIntegrate(double seed[3], double lastPoint[3], double stepSize, vtkAbstractInterpolatedVelocityField *func)
~vtkStreamTracer() override
void AddInput(vtkDataObject *)
vtkInitialValueProblemSolver * Integrator
void SetInterpolatorPrototype(vtkAbstractInterpolatedVelocityField *ivf)
The object used to interpolate the velocity field during integration is of the same class as this pro...
void SetIntegrationStepUnit(int unit)
Specify a uniform integration step unit for MinimumIntegrationStep, InitialIntegrationStep,...
void SetIntegratorType(int type)
Set/get the integrator type to be used for streamline generation.
int GetIntegrationStepUnit()
@ points
Definition: vtkX3D.h:446
@ direction
Definition: vtkX3D.h:260
@ type
Definition: vtkX3D.h:516
static double ConvertToLength(double interval, int unit, double cellLength)
static double ConvertToLength(vtkIntervalInformation &interval, double cellLength)
boost::graph_traits< vtkGraph * >::vertex_descriptor source(boost::graph_traits< vtkGraph * >::edge_descriptor e, vtkGraph *)
bool(* CustomTerminationCallbackType)(void *clientdata, vtkPoints *points, vtkDataArray *velocity, int integrationDirection)
Used to specify custom conditions which are evaluated to determine whether a streamline should be ter...
int vtkIdType
Definition: vtkType.h:315