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
82 #ifndef vtkStreamTracer_h
83 #define vtkStreamTracer_h
84 
85 #include "vtkFiltersFlowPathsModule.h" // For export macro
86 #include "vtkPolyDataAlgorithm.h"
87 
88 #include "vtkDataSetAttributesFieldList.h" // Needed to identify common data arrays
89 #include "vtkInitialValueProblemSolver.h" // Needed for constants
90 
91 VTK_ABI_NAMESPACE_BEGIN
94 class vtkDataArray;
96 class vtkDoubleArray;
97 class vtkExecutive;
98 class vtkGenericCell;
99 class vtkIdList;
100 class vtkIntArray;
101 class vtkPoints;
102 
103 VTK_ABI_NAMESPACE_END
104 #include <vector> // for std::vector
105 
106 // Helper struct to convert between different length scales.
107 VTK_ABI_NAMESPACE_BEGIN
108 struct VTKFILTERSFLOWPATHS_EXPORT vtkIntervalInformation
109 {
110  double Interval;
111  int Unit;
112 
113  static double ConvertToLength(double interval, int unit, double cellLength);
114  static double ConvertToLength(vtkIntervalInformation& interval, double cellLength);
115 };
116 
128  void* clientdata, vtkPoints* points, vtkDataArray* velocity, int integrationDirection);
129 
130 class VTKFILTERSFLOWPATHS_EXPORT vtkStreamTracer : public vtkPolyDataAlgorithm
131 {
132 public:
140  static vtkStreamTracer* New();
141 
143 
147  void PrintSelf(ostream& os, vtkIndent indent) override;
149 
151 
156  vtkSetVector3Macro(StartPosition, double);
157  vtkGetVector3Macro(StartPosition, double);
159 
161 
170 
177 
178  // The previously-supported TIME_UNIT is excluded in this current
179  // enumeration definition because the underlying step size is ALWAYS in
180  // arc length unit (LENGTH_UNIT) while the 'real' time interval (virtual
181  // for steady flows) that a particle actually takes to trave in a single
182  // step is obtained by dividing the arc length by the LOCAL speed. The
183  // overall elapsed time (i.e., the life span) of the particle is the sum
184  // of those individual step-wise time intervals. The arc-length-to-time
185  // conversion only occurs for vorticity computation and for generating a
186  // point data array named 'IntegrationTime'.
187  enum Units
188  {
189  LENGTH_UNIT = 1,
190  CELL_LENGTH_UNIT = 2
191  };
192 
193  enum Solvers
194  {
199  UNKNOWN
200  };
201 
203  {
207  OUT_OF_LENGTH = 4,
208  OUT_OF_STEPS = 5,
209  STAGNATION = 6,
210  FIXED_REASONS_FOR_TERMINATION_COUNT
211  };
212 
214 
225  vtkGetObjectMacro(Integrator, vtkInitialValueProblemSolver);
228  void SetIntegratorTypeToRungeKutta2() { this->SetIntegratorType(RUNGE_KUTTA2); }
229  void SetIntegratorTypeToRungeKutta4() { this->SetIntegratorType(RUNGE_KUTTA4); }
230  void SetIntegratorTypeToRungeKutta45() { this->SetIntegratorType(RUNGE_KUTTA45); }
232 
243 
251 
253 
256  vtkSetMacro(MaximumPropagation, double);
257  vtkGetMacro(MaximumPropagation, double);
259 
266  void SetIntegrationStepUnit(int unit);
267  int GetIntegrationStepUnit() { return this->IntegrationStepUnit; }
268 
270 
277  vtkSetMacro(InitialIntegrationStep, double);
278  vtkGetMacro(InitialIntegrationStep, double);
280 
282 
288  vtkSetMacro(MinimumIntegrationStep, double);
289  vtkGetMacro(MinimumIntegrationStep, double);
291 
293 
299  vtkSetMacro(MaximumIntegrationStep, double);
300  vtkGetMacro(MaximumIntegrationStep, double);
302 
304 
307  vtkSetMacro(MaximumError, double);
308  vtkGetMacro(MaximumError, double);
310 
312 
320  vtkSetMacro(MaximumNumberOfSteps, vtkIdType);
321  vtkGetMacro(MaximumNumberOfSteps, vtkIdType);
323 
325 
329  vtkSetMacro(TerminalSpeed, double);
330  vtkGetMacro(TerminalSpeed, double);
332 
334 
337  vtkGetMacro(SurfaceStreamlines, bool);
338  vtkSetMacro(SurfaceStreamlines, bool);
339  vtkBooleanMacro(SurfaceStreamlines, bool);
341 
342  enum
343  {
346  BOTH
347  };
348 
349  enum
350  {
352  INTERPOLATOR_WITH_CELL_LOCATOR
353  };
354 
356 
363  vtkSetClampMacro(IntegrationDirection, int, FORWARD, BOTH);
364  vtkGetMacro(IntegrationDirection, int);
365  void SetIntegrationDirectionToForward() { this->SetIntegrationDirection(FORWARD); }
366  void SetIntegrationDirectionToBackward() { this->SetIntegrationDirection(BACKWARD); }
367  void SetIntegrationDirectionToBoth() { this->SetIntegrationDirection(BOTH); }
369 
371 
376  vtkSetMacro(ComputeVorticity, bool);
377  vtkGetMacro(ComputeVorticity, bool);
379 
381 
385  vtkSetMacro(RotationScale, double);
386  vtkGetMacro(RotationScale, double);
388 
399 
409  void SetInterpolatorType(int interpType);
410 
412 
416  vtkGetMacro(ForceSerialExecution, bool);
417  vtkSetMacro(ForceSerialExecution, bool);
418  vtkBooleanMacro(ForceSerialExecution, bool);
420 
430  CustomTerminationCallbackType callback, void* clientdata, int reasonForTermination);
431 
441  double& step, double& minStep, double& maxStep, int direction, double cellLength);
442 
444 
448  void GenerateNormals(vtkPolyData* output, double* firstNormal, const char* vecName);
450  vtkGenericCell* cell, double pcoords[3], vtkDoubleArray* cellVectors, double vorticity[3]);
452 
454 
464  vtkSetMacro(UseLocalSeedSource, bool);
465  vtkGetMacro(UseLocalSeedSource, bool);
466  vtkBooleanMacro(UseLocalSeedSource, bool);
468 
469 protected:
471  ~vtkStreamTracer() override;
472 
473  // Create a default executive.
475 
476  // hide the superclass' AddInput() from the user and the compiler
478  {
479  vtkErrorMacro(<< "AddInput() must be called with a vtkDataSet not a vtkDataObject.");
480  }
481 
484 
485  void Integrate(vtkPointData* inputData, vtkPolyData* output, vtkDataArray* seedSource,
486  vtkIdList* seedIds, vtkIntArray* integrationDirections,
487  vtkAbstractInterpolatedVelocityField* func, int maxCellSize, int vecType,
488  const char* vecFieldName, double& propagation, vtkIdType& numSteps, double& integrationTime,
489  std::vector<CustomTerminationCallbackType>& customTerminationCallback,
490  std::vector<void*>& customTerminationClientData, std::vector<int>& customReasonForTermination);
491 
492  double SimpleIntegrate(double seed[3], double lastPoint[3], double stepSize,
494  int CheckInputs(vtkAbstractInterpolatedVelocityField*& func, int* maxCellSize);
495 
497 
498  // starting from global x-y-z position
499  double StartPosition[3];
500 
501  static const double EPSILON;
503 
504  // Used by subclasses, leave alone
506 
511 
512  int SetupOutput(vtkInformation* inInfo, vtkInformation* outInfo);
513  void InitializeSeeds(vtkDataArray*& seeds, vtkIdList*& seedIds,
514  vtkIntArray*& integrationDirections, vtkDataSet* source);
515 
518 
519  // Prototype showing the integrator type to be set by the user.
521 
522  double MaximumError;
524 
527 
528  // Compute streamlines only on surface.
530 
532 
533  // These are used to manage complex input types such as
534  // multiblock / composite datasets. Basically the filter input is
535  // converted to a composite dataset, and the point data attributes
536  // are intersected to produce a common set of output data arrays.
537  vtkCompositeDataSet* InputData; // convert input data to composite dataset
538  vtkDataSetAttributesFieldList InputPD; // intersect attributes of all datasets
539  bool
540  HasMatchingPointAttributes; // does the point data in the multiblocks have the same attributes?
541 
542  // Control execution as serial or threaded
544  bool SerialExecution; // internal use to combine information
545 
546  std::vector<CustomTerminationCallbackType> CustomTerminationCallback;
547  std::vector<void*> CustomTerminationClientData;
548  std::vector<int> CustomReasonForTermination;
549 
550  // Only relevant for this derived parallel version of vtkStreamTracer,
551  // but needs to be defined in this class to have a uniform interface
552  // between this class and the parallel override vtkPStreamTracer
554 
555  friend class PStreamTracerUtils;
556 
557 private:
558  vtkStreamTracer(const vtkStreamTracer&) = delete;
559  void operator=(const vtkStreamTracer&) = delete;
560 };
561 
562 VTK_ABI_NAMESPACE_END
563 #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:45
general representation of visualization data
Definition: vtkDataObject.h:55
helps manage arrays from multiple vtkDataSetAttributes.
represent and manipulate attribute data in a dataset
abstract class to specify dataset behavior
Definition: vtkDataSet.h:53
dynamic, self-adjusting array of double
Superclass for all pipeline executives in VTK.
Definition: vtkExecutive.h:39
provides thread-safe access to cells
list of point or cell ids
Definition: vtkIdList.h:23
a simple class to control print indentation
Definition: vtkIndent.h:29
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:35
represent and manipulate point attribute data
Definition: vtkPointData.h:30
represent and manipulate 3D points
Definition: vtkPoints.h:29
Superclass for algorithms that produce only polydata as output.
concrete dataset represents vertices, lines, polygons, and triangle strips
Definition: vtkPolyData.h:80
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